> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/changelog.md).

# Changelog

## 2026 Q4 Changelog

<table><thead><tr><th width="145.77783203125">Date (YYYY-MM-DD)</th><th width="145.4443359375">Category</th><th>Notes</th></tr></thead><tbody><tr><td>2026-10-30</td><td><a href="https://developers.bead.xyz/payments">Payments</a>, <a href="https://developers.bead.xyz/quick-start">Quick Start</a></td><td>Added <a href="https://developers.bead.xyz/payments/android-app-integration">Android App Integration</a>, a guide for native Android apps that load the hosted payment page in a WebView. It covers the required WebView settings, exposing the <code>ReactNativeWebView</code> interface so the hosted page can signal your app to close the WebView, returning to your app with a <code>redirectUrl</code> deep link, and confirming the outcome with polling or webhooks. Added a pointer to the new page from <a href="https://developers.bead.xyz/quick-start">Quick Start</a> and <a href="https://developers.bead.xyz/payments/create-payment">Create Payment</a>. Web and digital integrations are not affected.</td></tr><tr><td>2026-10-09</td><td><a href="https://developers.bead.xyz/reference-guide">Reference Guide</a></td><td><strong>OpenAPI file requires a Bead login.</strong> Updated Download OpenAPI, Endpoint Index, and Integration Support to note that the OpenAPI JSON file is available to registered partners with a Bead login, and that partners without a login can request access from Integration Support at support@bead.xyz. Added guidance to download the file while signed in before importing it into tools or attaching it for a coding agent. Removed the stale reference to Postman collections.</td></tr><tr><td>2026-10-08</td><td><a href="https://developers.bead.xyz/payments">Payments</a>, <a href="https://developers.bead.xyz/reference-guide">Reference Guide</a>, <a href="https://developers.bead.xyz/reporting">Reporting</a>, <a href="https://developers.bead.xyz/onboarding">Onboarding</a>, <a href="https://developers.bead.xyz/testing">Testing</a>, <a href="https://developers.bead.xyz/split-funding">Split Funding</a>, <a href="https://developers.bead.xyz/faqs-and-troubleshooting">FAQs</a></td><td><strong>Change to <code>overpaid</code> handling, and new reclaim tracking.</strong> <code>overpaid</code> is a paid outcome: fulfill the order. The requested amount settles to the merchant and only the excess is returned to the payer through reclaim. <code>underpaid</code> is not paid: treat it as declined, do not fulfill, and offer the customer a new payment. The amount sent is returned through reclaim. Every status other than <code>created</code> and <code>processing</code> is final. A reclaim does not change <code>statusCode</code>. Reclaim progress is reported in <code>refundLifecycleStatus</code>, <code>refundInitiatedAt</code>, <code>refundCompletedAt</code>, and <code>refundFailureReason</code>, which are returned by <code>GET /Payments/{paymentId}/tracking</code>, payment webhooks, and merchant and partner payment history. Bead sends a payment webhook each time <code>refundLifecycleStatus</code> changes, and partners can register the new <code>reclaimStatusChanged</code> partner webhook event. <code>partiallyRefunded</code> and <code>fullyRefunded</code> are reserved and not returned. The payment webhook idempotency key is now <code>paymentId</code> + <code>statusCode</code> + <code>refundLifecycleStatus</code>, because reclaim progress events repeat the same <code>statusCode</code>. A very small overpayment within a per tender tolerance is classified as <code>completed</code>. Reclaims below the network transfer minimum, such as 1 USDC, cannot be sent. The reclaim window on <a href="https://developers.bead.xyz/reference-guide/payment-scenarios/expired-payment-handling">Expired Payment Handling</a> is corrected to 30 days from the last update. <strong>Deprecations.</strong> <code>POST /Payments</code> is now the documented create payment endpoint across the site. <code>POST /Payments/crypto</code> is deprecated, still supported, and accepts the same request body, including <code>splitFunding</code> and <code>webhookUrls</code>. Also marked deprecated and still supported: <code>GET /Payments</code> (use <code>GET /Merchants/{id}/payments</code> or <code>GET /Partners/{id}/payments</code>, or <code>GET /Payments/{paymentId}/tracking</code> for a single payment), <code>GET /Payments/get-by-payment-code</code> (use the <code>PaymentCode</code> filter on payment history), <code>GET /Payments/tracking/{trackingId}</code>, and <code>GET /Merchants/all</code>. Documented <code>fundingStatus</code> (<code>pending</code>, <code>dispatched</code>, <code>paid</code>, <code>error</code>) and <code>fundingPaidAt</code> on <a href="https://developers.bead.xyz/reporting/merchant-payments">Merchant Payments</a> and <a href="https://developers.bead.xyz/reporting/partner-payments">Partner Payments</a>. These fields describe funding from the payment provider into Bead, not the merchant deposit. The <a href="https://developers.bead.xyz/reference-guide/operational-guides/using-an-llm-or-agent-to-build-a-payments-poc">LLM POC prompt</a> now points to the current OpenAPI URL. Updated <a href="https://developers.bead.xyz/payments/payment-statuses">Payment Statuses</a>, <a href="https://developers.bead.xyz/payments/payment-webhooks">Payment Webhooks</a>, <a href="https://developers.bead.xyz/payments/payment-status-response-examples">Payment Status Response Examples</a>, <a href="https://developers.bead.xyz/payments/create-payment">Create Payment</a>, <a href="https://developers.bead.xyz/quick-start">Quick Start</a>, <a href="https://developers.bead.xyz/reference-guide/payment-scenarios">Payment Scenarios</a>, <a href="https://developers.bead.xyz/reference-guide/payment-scenarios/under-and-over-payment-handling">Under and Over Payment Handling</a>, <a href="https://developers.bead.xyz/reference-guide/payment-scenarios/reclaiming-unconverted-crypto">Reclaiming Unconverted Crypto</a>, <a href="https://developers.bead.xyz/reference-guide/payment-scenarios/tracking-reclaim-status">Tracking Reclaim Status</a>, <a href="https://developers.bead.xyz/reference-guide/payment-scenarios/refunds-for-crypto-and-wallet-payments">Refunds for Crypto and Wallet Payments</a>, <a href="https://developers.bead.xyz/onboarding/partner-webhooks">Partner Webhooks</a>, <a href="https://developers.bead.xyz/reference-guide/operational-guides/webhook-event-reference">Webhook Event Reference</a>, <a href="https://developers.bead.xyz/reporting/payment-history-concepts/pagination-and-sorting">Pagination and Sorting</a>, <a href="https://developers.bead.xyz/authentication">Authentication</a>, <a href="https://developers.bead.xyz/reference-guide/core-concepts/environments-and-base-urls">Environments &#x26; Base URLs</a>, <a href="https://developers.bead.xyz/testing/test-with-klarna-recommended">Test with Klarna</a>, <a href="https://developers.bead.xyz/testing/test-with-paypal">Test with PayPal</a>, <a href="https://developers.bead.xyz/testing/test-crypto-payments">Test Crypto Payments</a>, <a href="https://developers.bead.xyz/reference-guide/enumerations-and-schemas/common-field-types">Common Field Types</a>, <a href="https://developers.bead.xyz/split-funding">Split Funding</a>, <a href="https://developers.bead.xyz/reference-guide/endpoint-index/table-view-all-apis">Endpoint Index Table View</a>, and the related FAQs.</td></tr><tr><td>2026-10-01</td><td><a href="https://developers.bead.xyz/onboarding">Onboarding</a>, <a href="https://developers.bead.xyz/faqs-and-troubleshooting">FAQs</a></td><td>Added <a href="https://developers.bead.xyz/onboarding/draft-and-submit">Draft and Submit (Recommended)</a>, the recommended pattern for starting every merchant onboarding application. Save a Draft with <code>POST /merchant-onboarding/applications/drafts</code>, update it with <code>PUT /merchant-onboarding/applications/drafts/{applicationId}</code>, attach PDF documents, then submit with <code>POST /merchant-onboarding/applications/{applicationId}/submit</code>. A Draft can be discarded with <code>DELETE /merchant-onboarding/applications/drafts/{applicationId}</code>. Draft requests wrap merchant fields in <code>merchantData</code>, require only <code>partnerId</code> and <code>merchantName</code>, reject unknown properties with a <code>400</code>, and do not accept <code>submitImmediately</code>. Updated <a href="https://developers.bead.xyz/onboarding">Onboarding</a>, <a href="https://developers.bead.xyz/onboarding/submit-application">Submit Application</a>, <a href="https://developers.bead.xyz/onboarding/application-attachments">Application Attachments</a>, <a href="https://developers.bead.xyz/onboarding/sample-payload">Sample Payload</a>, <a href="https://developers.bead.xyz/onboarding/cancel-application">Cancel Application</a>, the related FAQs, and the <a href="https://developers.bead.xyz/reference-guide/endpoint-index/table-view-all-apis">Endpoint Index Table View</a> to recommend the draft flow. <code>POST /merchant-onboarding/applications</code> and <code>POST /merchant-onboarding/applications-short</code> remain available and fully supported, so existing integrations do not need to change.</td></tr></tbody></table>

## 2026 Q3 Changelog

<table><thead><tr><th width="145.77783203125">Date (YYYY-MM-DD)</th><th width="145.4443359375">Category</th><th>Notes</th></tr></thead><tbody><tr><td>2026-09-29</td><td><a href="https://developers.bead.xyz/payments">Payments</a>, <a href="https://developers.bead.xyz/reference-guide">Reference Guide</a>, <a href="https://developers.bead.xyz/faqs-and-troubleshooting">FAQs</a></td><td>Documented the <code>abandoned</code> payment status. A payment that was created but never started is closed automatically as <code>abandoned</code>, which is a final, non-success status. It is available from <code>GET /Payments/{paymentId}/tracking</code> and is not currently delivered as a payment webhook event, so reconcile pending orders with the tracking endpoint. Updated <a href="https://developers.bead.xyz/payments/payment-statuses">Payment Statuses</a>, <a href="https://developers.bead.xyz/payments/payment-webhooks">Payment Webhooks</a>, and <a href="https://developers.bead.xyz/reference-guide/payment-scenarios/expired-payment-handling">Expired Payment Handling</a>, and added <a href="https://developers.bead.xyz/faqs-and-troubleshooting/payments-faqs/why-is-my-payment-still-created-or-in-progress">Why is my payment still Created or In Progress?</a>. Payment status checks now consistently use <code>paymentId</code> and <code>GET /Payments/{paymentId}/tracking</code>. <code>trackingId</code> and <code>GET /Payments/tracking/{trackingId}</code> are legacy, deprecated, and still supported for backward compatibility. Updated <a href="https://developers.bead.xyz/quick-start">Quick Start</a>, <a href="https://developers.bead.xyz/reference-guide/core-concepts/environments-and-base-urls">Environments &#x26; Base URLs</a>, <a href="https://developers.bead.xyz/reference-guide/endpoint-index/table-view-all-apis">Table View (All APIs)</a>, and <a href="https://developers.bead.xyz/payments/payment-status-response-examples">Payment Status Response Examples</a> to match. The recommended payment webhook idempotency key is now <code>paymentId</code> + <code>statusCode</code> everywhere it appears, including <a href="https://developers.bead.xyz/reference-guide/operational-guides/webhook-event-reference">Webhook Event Reference</a>, Expired Payment Handling, <a href="https://developers.bead.xyz/faqs-and-troubleshooting/environment-and-testing/how-to-test-klarna-payments">How to Test Klarna Payments</a>, and the webhook FAQs.</td></tr><tr><td>2026-09-26</td><td><a href="https://developers.bead.xyz/reference-guide">Reference Guide</a>, <a href="https://developers.bead.xyz/payments">Payments</a>, <a href="https://developers.bead.xyz/entity-management">Entity Management</a></td><td>Added <a href="https://developers.bead.xyz/reference-guide/payment-flows/in-person-payments-physical-terminals">In-Person Payments (Physical Terminals)</a>, a guide to building in-person checkouts on physical terminals. Cross-linked from <a href="https://developers.bead.xyz/payments">Payments</a>, <a href="https://developers.bead.xyz/payments/create-payment">Create Payment</a>, <a href="https://developers.bead.xyz/entity-management/terminal-management/terminal-lifecycle-concepts">Terminal Lifecycle (Concepts)</a>, <a href="https://developers.bead.xyz/reference-guide/payment-flows">Payment Flows</a>, and <a href="https://developers.bead.xyz/reference-guide/payment-flows/choosing-tender-types-by-payment-environment">Choosing Tender Types by Payment Environment</a>.</td></tr><tr><td>2026-09-21</td><td><a href="https://developers.bead.xyz/payments">Payments</a>, <a href="https://developers.bead.xyz/entity-management">Entity Management</a>, <a href="https://developers.bead.xyz/settlement">Settlement</a></td><td>Split funding field renames, now reflected across the documentation. Merchant enrollment is set with <code>setSplitFundingEnabled</code> on <a href="https://developers.bead.xyz/entity-management/merchant-management/update-merchant">Update Merchant</a> and read back as <code>isSplitFundingEnabled</code> on the flat <code>merchant</code> node of <a href="https://developers.bead.xyz/entity-management/merchant-management/get-merchant">Get Merchant</a>. The former names <code>setRebateProgramEnabled</code> and <code>isRebateProgramEnabled</code> are <strong>not aliased</strong>: a request that still sends the old name is dropped by the deserializer, returns a successful <code>200</code>, and enables nothing, so read the merchant back to confirm enrollment applied. On payment creation the request object is now <code>splitFunding</code>; <code>rebate</code> is still accepted during a transition window, but sending both on the same request is rejected. Inside the wrapper the amount field is <code>partnerPortion</code>, with no <code>targetRebate</code> alias. See <a href="https://developers.bead.xyz/split-funding">Split Funding</a> and <a href="https://developers.bead.xyz/payments/create-payment">Create Payment</a>. On the settlement and batch reports, <code>rebateTransactionCount</code> is now <code>splitFundingTransactionCount</code>; that field and <code>partnerPortion</code> are report row fields, not fields on the settlement or batch records. See <a href="https://developers.bead.xyz/settlement/settlements">Settlements</a> and <a href="https://developers.bead.xyz/settlement/batches">Batches</a>. Reporting route paths and CSV filename prefixes are unchanged.</td></tr><tr><td>2026-09-20</td><td><a href="https://developers.bead.xyz/payments">Payments</a>, <a href="https://developers.bead.xyz/reporting">Reporting</a>, <a href="https://developers.bead.xyz/settlement">Settlement</a></td><td>The Rebate Program has been renamed the <strong>Split Funding Program</strong>. Mechanics, request shape, validation rules and settlement behavior are unchanged. The documentation now has its own section: the program page is at <a href="https://developers.bead.xyz/split-funding">Split Funding</a> and the reports page at <a href="https://developers.bead.xyz/split-funding/reports">Split Funding Reports</a>. Redirects are in place from the previous URLs. Terminology was updated across <a href="https://developers.bead.xyz/payments/create-payment">Create Payment</a>, <a href="https://developers.bead.xyz/settlement/settlements">Settlements</a>, <a href="https://developers.bead.xyz/settlement/batches">Batches</a>, <a href="https://developers.bead.xyz/settlement/residual-reporting">Residual Reporting</a>, <a href="https://developers.bead.xyz/reporting">Reporting</a>, <a href="https://developers.bead.xyz/entity-management/merchant-management/get-merchant">Get Merchant</a> and <a href="https://developers.bead.xyz/entity-management/merchant-management/update-merchant">Update Merchant</a>. The Split Funding page now also states what the program requires of an integrator: it is normally operated with a consumer fee that the integrator sizes, discloses and presents itself, per tender. Bead does not calculate consumer fees and has no consumer fee capability; see <a href="https://developers.bead.xyz/faqs-and-troubleshooting/payments-faqs/consumer-fee-passthrough-for-wallet-and-crypto-tenders">Consumer Fee Passthrough for Wallet and Crypto Tenders</a>.</td></tr><tr><td>2026-09-15</td><td><a href="https://developers.bead.xyz/payments">Payments</a></td><td>Corrected <a href="https://developers.bead.xyz/payments/payment-webhooks">Payment Webhooks</a> to align with <a href="https://developers.bead.xyz/payments/payment-statuses">Payment Statuses</a>: <code>paymentId</code> is the primary payment identifier (<code>trackingId</code> was replaced on 2026-06-02), and the recommended webhook de-duplication key is <code>paymentId</code> + <code>statusCode</code>. <code>trackingId</code> remains on webhook payloads for backward compatibility but is deprecated.</td></tr><tr><td>2026-09-10</td><td><a href="https://developers.bead.xyz/payments">Payments</a></td><td>Refined <a href="https://developers.bead.xyz/split-funding">Rebate Program</a>: fee components, fee calculation timing, small-ticket break-even, underwater payment and distribution blocking behaviour, consumer fee ownership, and merchant rate configuration. Updated <a href="https://developers.bead.xyz/settlement/residual-reporting">Residual Reporting</a> for rebate distribution reporting.</td></tr><tr><td>2026-09-08</td><td><a href="https://developers.bead.xyz/payments">Payments</a>, <a href="https://developers.bead.xyz/reporting">Reporting</a>, <a href="https://developers.bead.xyz/settlement">Settlement</a></td><td>Documented the <a href="https://developers.bead.xyz/split-funding">Rebate Program</a>: added Rebate Program under <a href="https://developers.bead.xyz/payments">Payments</a>, covering the <code>rebate</code> request object (<code>total</code>, <code>merchantPortion</code>, <code>targetRebate</code>), the <code>merchantPortion + targetRebate = total</code> validation rule, Bead's rebate fee, enrollment via <a href="https://developers.bead.xyz/entity-management/merchant-management/update-merchant">Update Merchant's</a> <code>setRebateProgramEnabled</code> change, and partner distribution behavior. Added <a href="https://developers.bead.xyz/split-funding/reports">Rebate Reports</a> under Reporting, documenting the rebate transaction report and the rebate distribution summary (base, period, and account views). Replaced the "<a href="https://developers.bead.xyz/upcoming-changes/consumer-fee-control-and-exact-net-settlement">Consumer Fee Control and Exact Net Settlement</a>" page under Upcoming Changes, which described a <code>consumerFeeAmount</code>/<code>splitConfiguration</code> design that was never implemented; superseded by the Rebate Program above. Updated <a href="https://developers.bead.xyz/payments/create-payment">Create Payment</a>, <a href="https://developers.bead.xyz/settlement/settlements">Settlements</a>, <a href="https://developers.bead.xyz/settlement/batches">Batches</a>, and <a href="https://developers.bead.xyz/settlement/residual-reporting">Residual Reporting</a> to document rebate-related request fields, response fields, and reporting caveats. Updated <a href="https://developers.bead.xyz/entity-management/merchant-management/get-merchant">Get Merchant</a> to document <code>isRebateProgramEnabled</code>. Expanded <a href="https://developers.bead.xyz/entity-management/merchant-management/update-merchant">Update Merchant</a> to document the previously-undocumented <code>justification</code> field and the submit/approve/reject/cancel/get-single endpoints for merchant update requests, alongside the new <code>setRebateProgramEnabled</code> change.</td></tr><tr><td>2026-09-03</td><td><a href="https://developers.bead.xyz/reference-guide">Reference Guide</a>, <a href="https://developers.bead.xyz/entity-management">Entity Management</a>, <a href="https://developers.bead.xyz/faqs-and-troubleshooting">FAQs</a></td><td>Corrected webhook signature documentation to match live system behavior. Updated <a href="https://developers.bead.xyz/entity-management/terminal-management/webhook-management">Webhook Management</a>, <a href="https://developers.bead.xyz/reference-guide/operational-guides/webhook-event-reference">Webhook Event Reference</a>, and <a href="https://developers.bead.xyz/faqs-and-troubleshooting/webhooks-and-error-codes/can-i-send-webhook-events-to-multiple-urls">Can I send webhook events to multiple URLs?</a> to reflect that per-payment <code>webhookUrls</code> deliveries ARE signed with <code>x-webhook-signature</code> using the terminal's <code>signingSecret</code>, reversing the 2026-06-18 entry below, which was accurate at the time but predates a later change to the signing code path. Added the fail-open caveat: if a terminal has never had a webhook configured via <code>PUT /Terminals/{id}/webhook</code>, it has no signing secret, and its <code>webhookUrls</code> deliveries are sent unsigned with no error or warning. Corrected the FAQ's "identical signature for every recipient" claim: the body is identical across recipients, but each delivery is signed with its own timestamp, so signature values differ. Added a new FAQ, <a href="https://developers.bead.xyz/faqs-and-troubleshooting/webhooks-and-error-codes/why-is-x-webhook-signature-missing-from-some-webhook-deliveries">Why is x-webhook-signature missing from some webhook deliveries?</a>, covering this fail-open case directly and cross-linked it from the pages above.</td></tr><tr><td>2026-09-03</td><td><a href="https://developers.bead.xyz/onboarding">Onboarding</a>, <a href="https://developers.bead.xyz/entity-management">Entity Management</a></td><td>Added "Get a partner's fee schedule" to <a href="https://developers.bead.xyz/entity-management/partner-management">Partner Management</a>, documenting <code>GET /Partners/{id}/fee-schedule</code>: how a partner's fee schedule resolves through the account hierarchy (a partner without its own representing merchant inherits the schedule of its nearest ancestor that has one), the per-fee <code>sellRate</code>/<code>buyRate</code> shape, and the <code>404</code> case when neither the partner nor any ancestor has a representing merchant. Updated <a href="https://developers.bead.xyz/onboarding/fee-configuration-for-onboarding-applications">Fee Configuration for Onboarding Applications</a> to document that this schedule's <code>sellRate</code> values are the floor for merchant pricing, onboarding rejects a merchant fee sell rate below it, and added a new common mistake for pricing below the floor. Added a corresponding rule to <a href="https://developers.bead.xyz/onboarding/field-validation-rules">Field Validation Rules</a> under Pricing and tenders, and cross-linked the new endpoint from <a href="https://developers.bead.xyz/reference-guide/operational-guides/merchant-onboarding-guide">Merchant Onboarding Guide</a>.</td></tr><tr><td>2026-09-01</td><td><a href="https://developers.bead.xyz/onboarding">Onboarding</a>, <a href="https://developers.bead.xyz/faqs-and-troubleshooting">FAQs</a></td><td>Corrected the documented error response shape for <code>POST /merchant-onboarding/applications</code> and <code>POST /merchant-onboarding/applications-short</code> on <a href="https://developers.bead.xyz/onboarding/submit-application">Submit Application</a> and <a href="https://developers.bead.xyz/faqs-and-troubleshooting/webhooks-and-error-codes/how-do-i-resolve-a-400-validationerror">How do I resolve a 400 ValidationError?:</a> a <code>400</code> returns an RFC 9110 Problem Details object (<code>type</code>, <code>title</code>, <code>status</code>, <code>errors</code>, <code>traceId</code>), not the <code>code</code>/<code>error</code>/<code>message</code>/<code>details</code> envelope previously shown. Added a cross-reference on <a href="https://developers.bead.xyz/onboarding/field-validation-rules">Field Validation Rules</a> and flagged the exception on <a href="https://developers.bead.xyz/reference-guide/core-concepts/error-codes">Error Codes</a>.</td></tr><tr><td>2026-08-28</td><td><a href="https://developers.bead.xyz/faqs-and-troubleshooting">FAQs</a></td><td>Venmo testing is no longer available. Updated guidance accordingly on <a href="https://developers.bead.xyz/testing/test-with-venmo">Test with Venmo</a>, <a href="https://developers.bead.xyz/testing">Testing</a>, and <a href="https://developers.bead.xyz/testing/test-with-klarna-recommended">Test with Klarna (recommended)</a>.</td></tr><tr><td>2026-08-28</td><td><a href="https://developers.bead.xyz/entity-management">Entity Management</a></td><td>Corrected <code>locationBusinessType</code> irreversibility language on <a href="https://developers.bead.xyz/onboarding/submit-application">Submit Application</a> and <a href="https://developers.bead.xyz/entity-management/location-management">Location Management</a>: the value can change while an application is in flight, and adding an environment post-boarding is account maintenance that will likely trigger a new compliance review, not a resubmission. Noted that selecting <code>both</code> for a merchant that only needs one environment draws more review scrutiny, not less. Corrected <a href="https://developers.bead.xyz/onboarding/cancel-application">Cancel Application</a> to state that Draft applications are cancellable and that a successful cancel from <code>draft</code>, <code>viewed</code>, or <code>signing</code> always results in <code>withdrawn</code>. Updated <a href="https://developers.bead.xyz/faqs-and-troubleshooting/entity-management-faqs/can-i-delete-test-or-submitted-applications">Can I delete test or submitted applications?</a> to remove the claim that a cancellation status is a future feature request.</td></tr><tr><td>2026-08-28</td><td><a href="https://developers.bead.xyz/onboarding">Onboarding</a>, <a href="https://developers.bead.xyz/entity-management">Entity Management</a></td><td>Added "What boarding creates" to <a href="https://developers.bead.xyz/entity-management/location-management">Location Management</a>, documenting the automatic Location/Terminal creation at boarding keyed to <code>locationBusinessType</code>, with an extended Business types table and guidance on distinguishing default terminals from integrator-created ones. Corrected the <a href="https://developers.bead.xyz/reference-guide/operational-guides/merchant-onboarding-guide">Merchant Onboarding Guide</a> to retrieve and verify these defaults post-approval instead of instructing integrators to create them; endpoint, auth, and response-schema details remain flagged pending engineering confirmation.</td></tr><tr><td>2026-08-27</td><td><a href="https://developers.bead.xyz/onboarding">Onboarding</a></td><td>Updated <a href="https://developers.bead.xyz/onboarding/get-status">Get Status</a> to document the <code>onboardingExceptions</code> field returned on the application status response, including the exception object shape (<code>status</code>, <code>onboardingStep</code>, <code>exceptionType</code>, <code>errorMessage</code>, <code>timestamp</code>, <code>assignedTo</code>, <code>resolutionNotes</code>), the <code>open</code>/<code>inProgress</code>/<code>resolved</code> and <code>validationError</code>/<code>integrationFailure</code>/<code>crosswalkGap</code> enum values, and a worked example. Added the <code>viewed</code> status value to the status table and clarified that there is no <code>failed</code> status, use <code>changesRequested</code> or <code>rejected</code> with <code>onboardingExceptions</code> instead.</td></tr><tr><td>2026-08-21</td><td><a href="https://developers.bead.xyz/faqs-and-troubleshooting">FAQs</a></td><td>Added a <code>User-Agent: Bead-PaymentService/1.0</code> header to all outbound webhook requests (payment/terminal, onboarding, and settlement alike), applied uniformly at the delivery layer. Documented the header on <a href="https://developers.bead.xyz/faqs-and-troubleshooting/webhooks-and-error-codes/how-do-i-verify-that-a-webhook-really-came-from-bead">How do I verify that a webhook really came from Bead?</a> alongside the existing signature schemes, and added allowlisting guidance on <a href="https://developers.bead.xyz/faqs-and-troubleshooting/webhooks-and-error-codes/firewall-and-ip-allowlisting-for-webhooks">Firewall &#x26; IP Allowlisting for Webhooks</a> for partners whose WAF rejects requests without a <code>User-Agent</code> header.</td></tr><tr><td>2026-08-21</td><td><a href="https://developers.bead.xyz/reference-guide">Reference Guide</a>, <a href="https://developers.bead.xyz/entity-management">Entity Management</a></td><td>Added <a href="https://developers.bead.xyz/reference-guide/payment-flows/reading-tender-availability-at-runtime">Reading Tender Availability at Runtime</a> under Reference Guide › Payment Flows to give payment integrators a runtime pattern for <code>tenderTypes</code>: read <code>GET /Terminals/{terminalId}</code> at session or terminal-context start, cache for hours rather than per transaction, re-read after a tender-related payment failure, and always treat the live payment response, not the cache, as authoritative. Includes graceful-failure guidance for a consumer selecting an unavailable tender, reusing the same recovery pattern as underpaid/overpaid handling. Cross-linked from <a href="https://developers.bead.xyz/entity-management/terminal-management/managing-tender-types">Managing Tender Types</a> and <a href="https://developers.bead.xyz/reference-guide/payment-flows/choosing-tender-types-by-payment-environment">Choosing Tender Types by Payment Environment</a>, which continue to cover boarding-time configuration and business-context tender selection respectively.</td></tr><tr><td>2026-08-17</td><td><a href="https://developers.bead.xyz/payments">Payments</a></td><td>Corrected <code>customer</code> and <code>refundEmail</code> requirements on Create Payment: both required for virtual terminals, both optional for physical (with <code>customer.email</code> used automatically as a reclaim address when <code>refundEmail</code> is omitted on physical). Corrected the reclaim window on Reclaiming Unconverted Crypto to a single 30-day window from the payment's last update, not a 7/30-day split from creation.</td></tr><tr><td>2026-08-11</td><td><a href="https://developers.bead.xyz/settlement">Settlement</a>, <a href="https://developers.bead.xyz/faqs-and-troubleshooting">FAQs</a></td><td>Corrected Reporting query parameter documentation against the OpenAPI specification and live Test API: parameters are capitalized (<code>From</code>, <code>To</code>, <code>Page</code>, <code>PageSize</code>), <code>Page</code> is zero based, and <code>PageSize</code> has a maximum of 100. Clarified that <code>GET /Terminals/{id}/payments</code> returns a different response object than the merchant and partner payment endpoints, and documented the per scope field differences. Clarified that payment history does not include a <code>paymentSettlementStatusCode</code> field and is not filterable by it: use <code>settlementId</code>, <code>batchId</code>, <code>batchPeriod</code>, and <code>batchStatus</code> alongside the Settlement APIs.</td></tr><tr><td>2026-08-11</td><td><a href="https://developers.bead.xyz/reporting">Reporting</a></td><td>Aligned settlement record field documentation with the current schema, adding <code>batchCount</code>, <code>totalFees</code>, <code>netAdjustmentTotal</code>, <code>holdReason</code>, and <code>payoutId</code>, and removing <code>settlementSweepId</code>, <code>achTransferId</code>, and <code>targetPayoutDate</code>, which are not returned. Documented that <code>From</code> and <code>To</code> on the Settlement endpoints are date only values that filter on the settlement's <code>created</code> date. Noted that <code>MerchantIds</code> has no effect on <code>GET /Merchants/{merchantId}/settlements</code>: use <code>GET /Settlements</code> with <code>MerchantIds</code> for multi merchant queries.</td></tr><tr><td>2026-08-04</td><td><a href="https://developers.bead.xyz/onboarding">Onboarding</a></td><td>Clarified that Cancel/Withdraw is only available in <code>viewed</code>/<code>signing</code> status (not after submission); added missing <code>resubmitted</code> status and <code>409 Conflict</code> error case; cross-linked the two pages.</td></tr><tr><td>2026-07-30</td><td><a href="https://developers.bead.xyz/onboarding">Onboarding</a></td><td>Added <a href="https://developers.bead.xyz/onboarding/list-applications">List Applications</a> documenting <code>GET /Partners/{id}/applications</code>, and marked <code>GET /merchant-onboarding/applications</code> as deprecated in favor of it. Updated <a href="https://developers.bead.xyz/onboarding">Onboarding</a> and the <a href="https://developers.bead.xyz/reference-guide/endpoint-index/table-view-all-apis">Reference Guide Endpoint Index</a> to reflect the deprecation and the endpoint's correct location under Partners. Refreshed <a href="https://developers.bead.xyz/onboarding/get-status">Get Status</a> to add the <code>viewed</code> application status and its place in the signing flow (<code>signing → viewed → signed</code>), and to document the missing <code>404</code> error response.</td></tr><tr><td>2026-07-21</td><td><a href="https://developers.bead.xyz/settlement">Settlement</a></td><td>Updated <a href="https://developers.bead.xyz/settlement/settlement-reconciliation-patterns">Settlement Reconciliation Patterns</a> to correct the <code>GET /Settlements</code> <code>From</code>/<code>To</code> filter on <code>created</code>, not <code>updated</code>, and updated the incremental sync guidance to match.</td></tr><tr><td>2026-07-13</td><td><a href="https://developers.bead.xyz/entity-management">Entity Management</a></td><td>Updated terminal management documentation to make the <code>useSandboxSharedWallet</code> Sandbox requirement more visible. The setting is now called out explicitly on the <a href="https://developers.bead.xyz/entity-management/terminal-management/create-terminal">Create Terminal</a>, <a href="https://developers.bead.xyz/entity-management/terminal-management/update-terminal">Update Terminal</a>, <a href="https://developers.bead.xyz/faqs-and-troubleshooting/environment-and-testing/how-to-prepare-for-usdc-testing">How to Prepare for USDC Testing</a>, and <a href="https://developers.bead.xyz/faqs-and-troubleshooting/payments-faqs/troubleshooting-couldnt-create-payment-error">Troubleshooting "Couldn't Create Payment"</a> pages, including a note that the flag must be set at creation time and cannot be added to an existing terminal via the edit endpoint.</td></tr><tr><td>2026-07-13</td><td><a href="https://developers.bead.xyz/payments">Payments</a></td><td>Added guidance on the <code>conversions</code> array on the <a href="https://developers.bead.xyz/payments/receipts">Receipts</a> page, clarified it contains one entry by design, documented <code>statusCode</code> values, specified when to trust <code>executedExchangeRate</code>, and included a defensive read pattern.</td></tr><tr><td>2026-07-01</td><td><a href="https://developers.bead.xyz/settlement">Settlement</a></td><td>Removed the Merchant Settlements and Payment Settlements pages. The <code>/MerchantSettlements/</code> endpoints documented on those pages are deprecated and return empty results. Merchant settlement history is now available via <code>GET /Merchants/{merchantId}/settlements</code>. Payment-level settlement context is accessible through settlement fields (<code>settlementId</code>, <code>batchId</code>, <code>batchPeriod</code>, <code>batchStatus</code>) on the PaymentResponse and the batch path via <code>GET /Settlements/{id}/batches</code>. Added <a href="https://developers.bead.xyz/settlement/payment-settlement-detail">Payment Settlement Detail</a> to document the go-forward approach for connecting payments to settlement activity. Updated <a href="https://developers.bead.xyz/settlement">Settlement</a>, <a href="https://developers.bead.xyz/settlement/settlements">Settlements</a>, <a href="https://developers.bead.xyz/settlement/batches">Batches</a>, and <a href="https://developers.bead.xyz/settlement/deposits">Deposits</a> to remove stale cross-references and reflect current endpoints.</td></tr><tr><td>2026-07-01</td><td><a href="https://developers.bead.xyz/entity-management">Entity Management</a></td><td>Added <a href="https://developers.bead.xyz/entity-management/merchant-management/update-merchant">Update Merchant</a> to Merchant Management to document the merchant update request workflow, including create and list endpoints, draft versus immediate submission, scheduled and expiring changes, and request status lifecycle.</td></tr></tbody></table>

## 2026 Q2 Changelog

<table><thead><tr><th width="187.77783203125">Date (YYYY-MM-DD)</th><th width="145.4443359375">Category</th><th>Notes</th></tr></thead><tbody><tr><td>2026-06-24</td><td><a href="https://developers.bead.xyz/payments">Payments</a></td><td>Updated <a href="https://developers.bead.xyz/payments/test-crypto-transactions">Test Crypto Transactions</a> page content and added Lightning test payment guidance.</td></tr><tr><td>2026-06-24</td><td><a href="https://developers.bead.xyz/settlement">Settlement</a></td><td>Added <a href="https://developers.bead.xyz/settlement/testing-settlement-in-the-test-environment">Testing Settlement in the Test Environment</a> to document how BTC, Lightning, PayPal, Venmo, and Klarna payments progress through the settlement lifecycle in the test environment, including batch and settlement status progression, simulator schedule, and expected end state. Updated field documentation across <a href="https://developers.bead.xyz/settlement/settlements">Settlements</a>, Merchant Settlements, and Payment Settlements to align with current API schema.</td></tr><tr><td>2026-06-18</td><td><a href="https://developers.bead.xyz/reference-guide">Reference Guide</a>, <a href="https://developers.bead.xyz/faqs-and-troubleshooting">FAQs</a></td><td>Corrected webhook signature documentation to match live system behavior. Updated <code>x-webhook-signature</code> header format across <a href="https://developers.bead.xyz/reference-guide/operational-guides/webhook-event-reference">Webhook Event Reference</a>, <a href="https://developers.bead.xyz/entity-management/terminal-management/webhook-management">Webhook Management</a>, and <a href="https://developers.bead.xyz/faqs-and-troubleshooting/webhooks-and-error-codes/how-do-i-verify-that-a-webhook-really-came-from-bead">How do I verify that a webhook really came from Bead?</a> to reflect that <code>t</code> is a Unix epoch timestamp in milliseconds (not seconds) and <code>s</code> is a Base64-encoded HMAC-SHA256 digest (not hex). Updated the Node.js verification code example to use <code>.digest("base64")</code> and millisecond-based timestamp comparison. Corrected the <code>PUT /Terminals/{id}/webhook</code> request body field from <code>webhookUrl</code> to <code>url</code> and authentication header from OAuth Bearer to <code>X-Api-Key</code>. Replaced placeholder <code>signingSecret</code> example values with accurate format. Added explicit guidance that <code>x-webhook-signature</code> is present on terminal-level webhook deliveries only and is not included on per-payment <code>webhookUrls</code> deliveries.</td></tr><tr><td>2026-06-09</td><td><a href="https://developers.bead.xyz/settlement">Settlement</a>, <a href="https://developers.bead.xyz/reporting">Reporting</a></td><td>Added <a href="https://developers.bead.xyz/settlement/residual-reporting">Residual Reporting</a> and <a href="https://developers.bead.xyz/settlement/settlements">Settlements</a> to support partner fee revenue reporting. Expanded field-level documentation and corrected enum values across the Settlement section. Updated <a href="https://developers.bead.xyz/reporting">Reporting</a> and <a href="https://developers.bead.xyz/reporting/payment-history-concepts/pagination-and-sorting">Pagination and Sorting</a> with corrected query parameter names and additional filter options.</td></tr><tr><td>2026-06-01</td><td><a href="https://developers.bead.xyz/payments">Payments</a>, <a href="https://developers.bead.xyz/faqs-and-troubleshooting">FAQs</a></td><td>Added <a href="https://developers.bead.xyz/reference-guide/payment-scenarios/refunds-for-crypto-and-wallet-payments">Refunds for Crypto and Wallet Payments</a> to <a href="https://developers.bead.xyz/reference-guide/payment-scenarios">Payment Scenarios</a> covering why completed crypto, wallet, and BNPL payments have no API-level refund capability, how cash settlement and asset conversion work, regulatory constraints on outbound crypto transfers, and merchant return policy guidance. Updated Payment Statuses to clarify that <code>fullyRefunded</code> and <code>partiallyRefunded</code> are reserved and not currently returned, with a link to the new refund guidance. Added <a href="https://developers.bead.xyz/faqs-and-troubleshooting/payments-faqs/does-bead-support-a-refund-api-for-crypto-wallet-and-bnpl-payments">Does Bead support a refund API for crypto, wallet, and BNPL payments?</a> to Payments FAQs.</td></tr><tr><td>2026-05-21</td><td><a href="https://developers.bead.xyz/payments">Payments</a>, <a href="https://developers.bead.xyz/reference-guide">Reference Guide</a>, <a href="https://developers.bead.xyz/faqs-and-troubleshooting">FAQs</a></td><td>Added <a href="https://developers.bead.xyz/faqs-and-troubleshooting/payments-faqs/why-do-btc-on-chain-payments-take-longer">Why do BTC Classic payments take longer?</a> and <a href="https://developers.bead.xyz/reference-guide/payment-flows/choosing-tender-types-by-payment-environment">Choosing Tender Types by Payment Environment</a>. Refreshed <a href="https://developers.bead.xyz/payments/payment-statuses">Payment Statuses</a>, <a href="https://developers.bead.xyz/payments/create-payment">Create Payment</a>, <a href="https://developers.bead.xyz/payments/crypto-wallet-flow-and-amounts">Crypto Wallet Flow and Amounts</a>, <a href="https://developers.bead.xyz/payments/payment-webhooks">Payment Webhooks</a>, <a href="https://developers.bead.xyz/reference-guide/enumerations-and-schemas/tender-types">Tender Types</a>, and <a href="https://developers.bead.xyz/reference-guide/payment-flows">Payment Flows</a> to clarify BTC Classic / Bitcoin on-chain timing, <code>processing</code> versus <code>completed</code> handling, asynchronous customer experiences, webhook-driven completion, and fulfillment guidance for physical, digital, invoice, and delayed-delivery environments.</td></tr><tr><td>2026-05-06</td><td><a href="https://developers.bead.xyz/onboarding">Onboarding</a></td><td>Added <a href="https://developers.bead.xyz/onboarding/application-attachments">Application Attachments</a> documentation and refreshed the Onboarding documentation set to cover submitImmediately, Draft applications, attachment upload/list/download/delete workflows, POST /merchant-onboarding/applications/{applicationId}/submit for Draft submission, the distinction between Draft submit and resend, updated status lifecycle guidance, current short and full application sample payloads, and onboarding webhook configuration/event handling.</td></tr><tr><td>2026-04-27</td><td><a href="https://developers.bead.xyz/payments">Payments</a>,<br><a href="https://developers.bead.xyz/reference-guide">Reference Guide</a>,<br><a href="https://developers.bead.xyz/faqs-and-troubleshooting">FAQs</a></td><td>Updated crypto testing and payment documentation to clarify that Bead Sandbox crypto payments use live blockchain networks and require real assets plus real network fee tokens. Added consistent guidance that USDC on Base and USDC on Solana require a minimum Bead payment amount of $1.00 USD, separate from network fees. Refreshed related guidance across <a href="https://developers.bead.xyz/payments/create-payment">Create Payment</a>, <a href="https://developers.bead.xyz/quick-start">Quick Start</a>, <a href="https://developers.bead.xyz/payments">Payments</a>, <a href="https://developers.bead.xyz/payments/test-crypto-transactions">Test Crypto Transactions</a>, <a href="https://developers.bead.xyz/faqs-and-troubleshooting/environment-and-testing/crypto-payments-environment-and-testing">Crypto payments environment and testing</a>, <a href="https://developers.bead.xyz/faqs-and-troubleshooting/payments-faqs/crypto-testing-and-fees">Crypto Testing and Fees</a>, <a href="https://developers.bead.xyz/reference-guide/enumerations-and-schemas/tender-types/crypto">Crypto Tender Types</a> and <a href="https://developers.bead.xyz/reference-guide/operational-guides/compatible-crypto-wallets">Compatible Crypto Wallets</a>. Cleaned up stale testnet-oriented USDC guidance and aligned tender references for USDC on Base, USDC on Solana, Bitcoin on chain, and Bitcoin Lightning.</td></tr><tr><td>2026-04-21</td><td><a href="https://developers.bead.xyz/payments">Payments</a></td><td>Updated <a href="https://developers.bead.xyz/payments/create-payment">Create Payment</a>, <a href="https://developers.bead.xyz/payments">Payments</a>, and <a href="https://developers.bead.xyz/reference-guide/enumerations-and-schemas/tender-types">Tender Types</a> to clarify optional tender preselection on the hosted payment page, including default tender selection when <code>tenderTypes</code> is omitted and how <code>tenderTypes</code> can be used to preselect or constrain the hosted experience.</td></tr><tr><td>2026-04-10</td><td><a href="https://developers.bead.xyz/onboarding">Onboarding</a></td><td>Updated the Onboarding documentation set to align merchant onboarding request guidance with the current API schema. Refreshed <a href="https://developers.bead.xyz/onboarding/submit-application">Submit Application</a>, <a href="https://developers.bead.xyz/onboarding/sample-payload">Sample Payload</a>, and <a href="https://developers.bead.xyz/onboarding">Onboarding</a> to reflect the current full and short application patterns, including signer placement in <code>merchantData.stakeholders</code> for full applications and <code>signerFirstName</code>, <code>signerLastName</code>, and <code>signerEmail</code> for short applications, while preserving practical implementation guidance and current response examples.</td></tr><tr><td>2026-04-07</td><td><a href="https://developers.bead.xyz/onboarding">Onboarding</a></td><td>Added <a href="https://developers.bead.xyz/onboarding/fee-configuration-for-onboarding-applications">Fee Configuration for Onboarding Applications</a> and refreshed related onboarding examples to align <code>feeInformation</code>, <code>cryptoEnvironment</code>, and signer fields with the current schema. Clarified crypto as a single merchant-level fee structure, digital wallets as wallet-specific fee entries by tender and channel, and that missing wallet fee entries prevent those wallet tenders from being available for the merchant.</td></tr><tr><td>2026-04-07</td><td><a href="https://developers.bead.xyz/reference-guide">Reference Guide</a></td><td>Updated <a href="https://developers.bead.xyz/reference-guide/payment-scenarios">Payment Scenarios</a> and <a href="https://developers.bead.xyz/reference-guide/operational-guides">Operational Guides</a> to better separate payment outcome handling from supplemental operational guidance. Added <a href="https://developers.bead.xyz/reference-guide/payment-scenarios/refunds-for-crypto-and-wallet-payments">Refunds for Crypto and Wallet Payments</a> and refreshed underpaid, overpaid, reclaim, and section-level navigation guidance to align with current supported behavior.</td></tr><tr><td>2026-04-03</td><td><a href="https://developers.bead.xyz/entity-management">Entity Management</a></td><td>Refreshed <a href="https://developers.bead.xyz/entity-management/terminal-management">Terminal Management</a> authentication and lifecycle guidance to use admin API key headers for terminal-management operations and terminal payments API keys for payment activity.</td></tr><tr><td>2026-04-03</td><td><a href="https://developers.bead.xyz/entity-management">Entity Management</a></td><td>Updated <a href="https://developers.bead.xyz/entity-management/terminal-management/create-terminal">Create Terminal</a>, <a href="https://developers.bead.xyz/entity-management/terminal-management/list-terminals">List Terminals</a>, <a href="https://developers.bead.xyz/entity-management/terminal-management/get-terminal">Get Terminal</a>, <a href="https://developers.bead.xyz/entity-management/terminal-management/update-terminal">Update Terminal</a>, <a href="https://developers.bead.xyz/entity-management/terminal-management/delete-terminal">Delete Terminal</a>, and <a href="https://developers.bead.xyz/entity-management/terminal-management/webhook-management">Webhook Management</a> to align terminal docs with current request and response models.</td></tr><tr><td>2026-04-03</td><td><a href="https://developers.bead.xyz/entity-management">Entity Management</a></td><td>Added <a href="https://developers.bead.xyz/entity-management/terminal-management/reset-terminal-api-key">Reset Terminal API Key</a> to document terminal credential rotation and secure storage of the returned payments API key.</td></tr><tr><td>2026-04-01</td><td><a href="https://developers.bead.xyz/onboarding">Onboarding</a></td><td>Updated <a href="https://developers.bead.xyz/onboarding/webhooks-for-application-events">Webhooks for Application Events</a> to align onboarding webhook documentation with the current API, including <code>X-Api-Key</code> authentication, <code>POST /merchant-onboarding/{partnerId}/webhook</code> registration, returned <code>webhookSecret</code> handling, supported onboarding event types, and clearer guidance for verification, idempotent processing, follow-up status lookups, and webhook removal.</td></tr><tr><td>2026-04-01</td><td><a href="https://developers.bead.xyz/reference-guide">Reference Guide</a></td><td>Updated <a href="https://developers.bead.xyz/reference-guide">Reference Guide</a> to align shared authentication guidance with current documentation, clarify that onboarding and related admin or entity-management flows use <code>X-Api-Key</code> where documented, limit OAuth guidance to endpoint families that explicitly require it, and remove Postman-specific references from shared guidance.</td></tr><tr><td>2026-04-01</td><td><a href="https://developers.bead.xyz/reference-guide">Reference Guide</a></td><td>Updated <a href="https://developers.bead.xyz/reference-guide/endpoint-index/download-openapi">Download OpenAPI</a> to focus on OpenAPI-only guidance, remove Postman collection and environment setup references, and clarify how to use the OpenAPI specification for endpoint review, request validation, client generation, environments, and troubleshooting.</td></tr></tbody></table>

## 2026 Q1 Changelog

<table><thead><tr><th width="189.0001220703125">Date (YYYY-MM-DD)</th><th width="136.3333740234375">Category</th><th>Notes</th></tr></thead><tbody><tr><td>2026-03-31</td><td><a href="https://developers.bead.xyz/onboarding">Onboarding</a></td><td>Refreshed <a href="https://developers.bead.xyz/onboarding">Onboarding</a>, <a href="https://developers.bead.xyz/onboarding/submit-application">Submit Application</a>, and <a href="https://developers.bead.xyz/onboarding/sample-payload">Sample Payload</a> to align merchant onboarding guidance with the current API, including the plural application endpoints, the current full (<code>signer</code> + <code>merchantData</code>) and minimal (<code>signerName</code> / <code>signerEmail</code>) request shapes, required <code>cryptoEnvironment</code> usage for Sandbox versus Production, and the addition of <a href="https://developers.bead.xyz/onboarding/test-the-full-onboarding-workflow-in-sandbox">Test the Full Onboarding Workflow in Sandbox</a> for end-to-end testing guidance.</td></tr><tr><td>2026-03-31</td><td><a href="https://developers.bead.xyz/reference-guide">Reference Guide</a></td><td>Reworked <a href="https://developers.bead.xyz/reference-guide/enumerations-and-schemas/merchant-onboarding-schema">Merchant Onboarding Schema</a> to reflect the current onboarding create models, including the plural application endpoints, current full and minimal request shapes, required <code>cryptoEnvironment</code> values, updated fee structures, and current create response fields.</td></tr><tr><td>2026-03-31</td><td><a href="https://developers.bead.xyz/faqs-and-troubleshooting">FAQs</a></td><td>Clarified <a href="https://developers.bead.xyz/faqs-and-troubleshooting/environment-and-testing/sandbox-and-production-urls">Sandbox and production URLs</a> with environment-specific onboarding guidance, including API-key-based onboarding authentication, the required <code>cryptoEnvironment</code> field for onboarding create requests, and how to align Sandbox versus Production credentials and request values.</td></tr><tr><td>2026-03-31</td><td><a href="https://developers.bead.xyz/authentication">Authentication</a></td><td>Revised <a href="https://developers.bead.xyz/authentication">Authentication</a> to better distinguish API key versus OAuth usage across API families, align onboarding authentication guidance to the current API-key-based model, reference the current full and minimal onboarding request shapes, and document <code>cryptoEnvironment</code> as required for onboarding create requests.</td></tr><tr><td>2026-03-31</td><td><a href="https://developers.bead.xyz/introduction">Introduction</a></td><td>Aligned <a href="https://developers.bead.xyz/introduction">Introduction</a> with the current onboarding model by updating the overview and authentication guidance to reflect API-key-based onboarding, the current full versus minimal onboarding flows, and the required <code>cryptoEnvironment</code> setting for onboarding create requests.</td></tr><tr><td>2026-03-31</td><td><a href="https://developers.bead.xyz/onboarding">Onboarding</a></td><td>Added a new page: <a href="https://developers.bead.xyz/onboarding/test-the-full-onboarding-workflow-in-sandbox">Test the Full Onboarding Workflow in Sandbox</a>. Provides an end-to-end Sandbox testing guide covering application creation, signer completion, status checks, webhook validation, the manual Sandbox advance step, and boarded merchant confirmation.</td></tr><tr><td>2026-03-30</td><td><a href="https://developers.bead.xyz/reference-guide">Reference Guide</a></td><td>Updated <a href="https://developers.bead.xyz/reference-guide/operational-guides/webhook-event-reference">Webhook Event Reference</a> to better separate shared webhook delivery guidance from product-specific webhook payload documentation, including clearer coverage of terminal versus per-payment delivery paths, signature verification, retry and timeout behavior, idempotent processing, ordering expectations, and webhook security and operational best practices.</td></tr><tr><td>2026-03-30</td><td><a href="https://developers.bead.xyz/payments">Payments</a></td><td>Updated <a href="https://developers.bead.xyz/payments/payment-webhooks">Payment Webhooks</a> to include a concrete webhook payload example, field-by-field documentation, clearer guidance on using <code>trackingId</code> for correlation and follow-up status lookups, and stronger implementation guidance for signature verification, idempotent processing, and duplicate delivery handling.</td></tr><tr><td>2026-03-12</td><td><a href="https://developers.bead.xyz/payments">Payments</a><br><a href="https://developers.bead.xyz/reference-guide">Reference Guide</a></td><td>Updated to remove <code>paymentUrlType</code> references. This field is optional and not used, so this is a documentation cleanup only and does not introduce breaking behavior for existing integrations.</td></tr><tr><td>2026-03-07</td><td><a href="https://developers.bead.xyz/payments">Payments</a></td><td>Updated the <a href="https://developers.bead.xyz/payments">Payments</a> documentation set to align authentication and endpoint guidance across overview and workflow pages. Clarified that new Payments integrations use <code>X-Api-Key</code>, preserved legacy OAuth guidance only where applicable, corrected Payments endpoint references to <code>POST /Payments/crypto</code>, added clearer request guidance for terminals with <code>type</code> = <code>virtual</code> versus <code>type</code> = <code>physical</code>, refined <a href="https://developers.bead.xyz/payments/payment-statuses">Payment Statuses</a> to emphasize operational status handling and reclaim scenarios, and updated <a href="https://developers.bead.xyz/payments/payment-webhooks">Payment Webhooks</a> to reinforce webhook-first event handling and terminal webhook configuration using the supported methods.</td></tr><tr><td>2026-03-07</td><td><a href="https://developers.bead.xyz/onboarding">Onboarding</a></td><td>Updated <a href="https://developers.bead.xyz/onboarding/submit-application">Submit Application</a> to use the plural onboarding endpoints, align request guidance to <code>signerInfo</code>, clarify when to use the full versus minimal application flows, and reinforce that both flows use API-key-based onboarding requests and return identifiers for downstream status tracking.</td></tr><tr><td>2026-03-07</td><td><a href="https://developers.bead.xyz/faqs-and-troubleshooting">FAQs</a></td><td>Updated <a href="https://developers.bead.xyz/faqs-and-troubleshooting/environment-and-testing/how-to-test-klarna-payments">How to Test Klarna Payments</a> to use <code>X-Api-Key</code> header authentication, corrected Payments endpoint references to <code>POST /Payments/crypto</code>, and clarified Klarna request requirements by terminal <code>type</code>, including different minimum fields for <code>virtual</code> versus <code>physical</code> terminals.</td></tr><tr><td>2026-03-07</td><td><a href="https://developers.bead.xyz/faqs-and-troubleshooting">FAQs</a></td><td>Updated <a href="https://developers.bead.xyz/faqs-and-troubleshooting/environment-and-testing/sandbox-and-production-urls">Sandbox and production URLs</a> to clarify environment-specific base URLs and authentication patterns, distinguish Payments and onboarding API key usage from OAuth-based flows, correct the Payments reference to <code>POST /Payments/crypto</code>, and note that payment request field requirements can vary by terminal configuration and tender flow.</td></tr><tr><td>2026-03-07</td><td><a href="https://developers.bead.xyz/onboarding">Onboarding</a></td><td>Updated <a href="https://developers.bead.xyz/onboarding">Onboarding</a> to use the plural application endpoints, align onboarding terminology to <code>signerInfo</code>, clarify that API-initiated onboarding emails the merchant signer a secure link, and describe full versus minimal application flows using current API-key-based onboarding guidance.</td></tr><tr><td>2026-03-07</td><td><a href="https://developers.bead.xyz/onboarding">Onboarding</a></td><td>Refreshed <a href="https://developers.bead.xyz/onboarding/get-status">Get Status</a> to focus on the most important operational response fields such as <code>id</code>, <code>merchantName</code>, <code>status</code>, and <code>onboardedMerchantId</code>, align endpoint references to the plural onboarding paths, and remove unnecessary nested response detail in favor of the spec for full schema coverage.</td></tr><tr><td>2026-03-07</td><td><a href="https://developers.bead.xyz/onboarding">Onboarding</a></td><td>Updated <a href="https://developers.bead.xyz/onboarding/resend-application">Resend Application</a> to use the plural onboarding endpoints, clarify that the resend flow sends an existing application back to the same merchant signer for correction or completion, and position resend as a way to preserve the original application record while continuing the hosted onboarding flow.</td></tr><tr><td>2026-03-06</td><td><a href="https://developers.bead.xyz/introduction">Introduction</a></td><td>Clarified <a href="https://developers.bead.xyz/introduction">Introduction</a> authentication guidance across API families, aligned onboarding terminology to <code>signerInfo</code>, and noted that API-initiated onboarding emails the merchant signer a secure link.</td></tr><tr><td>2026-03-06</td><td><a href="https://developers.bead.xyz/authentication">Authentication</a></td><td>Updated <a href="https://developers.bead.xyz/faqs-and-troubleshooting/authentication-faqs">Authentication</a> to distinguish API key versus OAuth usage, added onboarding API key guidance, and corrected Payments endpoint references to <code>POST /Payments/crypto</code>.</td></tr><tr><td>2026-03-06</td><td><a href="https://developers.bead.xyz/entity-management">Entity Management</a></td><td>Refreshed <a href="https://developers.bead.xyz/entity-management">Entity Management</a> to better describe API purpose, align onboarding wording to <code>signerInfo</code>, and clarify authentication guidance for onboarding versus other flows.</td></tr><tr><td>2026-03-06</td><td><a href="https://developers.bead.xyz/entity-management/terminal-management">Terminal Management</a></td><td>Updated <a href="https://developers.bead.xyz/entity-management/terminal-management">Terminal Management</a> to correct the terminal update method to <code>PUT /Terminals/{id}</code> and clarify terminal lifecycle guidance, including update, disable, and delete behavior.</td></tr><tr><td>2026-02-27</td><td><a href="https://developers.bead.xyz/onboarding">Onboarding</a></td><td>Updated <a href="https://developers.bead.xyz/onboarding/webhooks-for-application-events">Webhooks for Application Events</a> to include webhook registration and deletion using onboarding API keys (X-Api-Key) with legacy bearer token examples retained, plus request/response samples for endpointUrl, eventTypes, and optional webhookSecret guidance.</td></tr><tr><td>2026-02-27</td><td><a href="https://developers.bead.xyz/faqs-and-troubleshooting">FAQs</a></td><td>Added <a href="https://developers.bead.xyz/faqs-and-troubleshooting/payments-faqs/can-i-view-payments-with-a-payment-api-key">Can I view payments with a Payment API key?</a> FAQ page with a terminalId-based payment history example (GET /Payments), plus pagination basics and a link to Pagination and sorting.</td></tr><tr><td>2026-02-23</td><td><a href="https://developers.bead.xyz/payments">Payments</a></td><td>Added a new page: <a href="https://developers.bead.xyz/payments/crypto-wallet-flow-and-amounts">Crypto Wallet Flow and Amounts</a>. Explains when consumers are expected to manually enter the amount after scanning a crypto QR code, and why some rails like Bitcoin Lightning can include the amount in the QR experience.</td></tr><tr><td>2026-02-20</td><td><a href="https://developers.bead.xyz/reference-guide">Reference Guide</a></td><td>Added <a href="https://developers.bead.xyz/reference-guide/conventions/identifiers-and-keys">Identifiers and Keys</a> guidance covering the expected formats for common IDs (for example merchantId and terminalId) and API keys, including simple format checks to help integrators catch copy paste errors early.</td></tr><tr><td>2026-02-10</td><td><a href="https://developers.bead.xyz/onboarding">Onboarding</a></td><td>Updated the <a href="https://developers.bead.xyz/onboarding/submit-application">Submit Application</a> documentation to match the current onboarding API schema. Revised field names and required fields, added location business type guidance, updated fee requirements to include monthlyMaintenanceFee and isBilledByPartner, corrected seasonality and MCC fields, and refreshed the full and minimal request examples plus cURL samples to validate against the latest spec.</td></tr><tr><td>2026-02-10</td><td><a href="https://developers.bead.xyz/payments">Payments</a></td><td>Added a new Payments documentation page: <a href="https://developers.bead.xyz/payments/receipts">Receipts</a>. Provides guidance on extending your existing POS or checkout receipt when supporting Bead payment methods, including which Bead reference value to display and how optional Bead delivered receipts work (<code>emailReceipt</code>, <code>smsReceipt</code>).</td></tr><tr><td>2026-01-30</td><td><a href="https://developers.bead.xyz/payments">Payments</a></td><td>Updated <a href="https://developers.bead.xyz/payments">Payments</a> documentation to clarify underpaid and overpaid behavior, including recommended integrator handling and reclaim outcomes.</td></tr><tr><td>2026-01-30</td><td><a href="https://developers.bead.xyz/reference-guide">Reference Guide</a></td><td>Updated <a href="https://developers.bead.xyz/reference-guide/payment-scenarios">Payment Scenarios</a> guidance for underpaid, overpaid, and reclaiming unconverted crypto to align with current product behavior and customer reclaim steps.</td></tr><tr><td>2026-01-30</td><td><a href="https://developers.bead.xyz/quick-start">Quick Start</a></td><td>Updated <a href="https://developers.bead.xyz/quick-start">Quick Start</a> to include underpayment and overpayment outcomes, reclaim email expectations, and recommended confirmation patterns.</td></tr><tr><td>2026-01-27</td><td><a href="https://developers.bead.xyz/faqs-and-troubleshooting">FAQs</a></td><td>Added <a href="https://developers.bead.xyz/faqs-and-troubleshooting/environment-and-testing/test-data-uniqueness-requirements">Test Data Guidelines: Email Addresses</a> page with guidance for automated testing to use valid, deliverable email addresses and to ensure each application uses a unique email (recommended plus addressing with timestamp or sequence counter) to reduce undeliverable email noise and duplicate email conflicts.</td></tr><tr><td>2026-01-19</td><td><a href="https://developers.bead.xyz/faqs-and-troubleshooting">FAQs</a></td><td>Clarified that applications cannot be deleted once submitted due to compliance requirements. Added guidance on managing test applications.<br><a href="https://developers.bead.xyz/faqs-and-troubleshooting/entity-management-faqs/can-i-delete-test-or-submitted-applications">Can I delete test or submitted applications?</a></td></tr><tr><td>2026-01-19</td><td><a href="https://developers.bead.xyz/reference-guide">Reference Guide</a></td><td>Removed references to client secrets and client credential grant flows from the documentation to reflect the current authentication models in use.</td></tr><tr><td>2026-01-19</td><td><a href="https://developers.bead.xyz/onboarding">Onboarding</a></td><td>Clarified required fields for minimal onboarding applications and updated the <a href="https://developers.bead.xyz/onboarding/sample-payload">Sample Payload</a> documentation to include full fee information, reflecting the minimum data needed for applications sent directly to signing.</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.bead.xyz/changelog.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
