> 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 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-15</td><td><a href="/payments.md">Payments</a></td><td>Corrected <a href="/payments/payment-webhooks.md">Payment Webhooks</a> to align with <a href="/payments/payment-statuses.md">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="/payments.md">Payments</a></td><td>Refined <a href="/payments/rebate-program.md">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="/settlement/residual-reporting.md">Residual
 Reporting</a> for rebate distribution reporting.</td></tr><tr><td>2026-09-08</td><td><a href="/payments.md">Payments</a>, <a href="/reporting.md">Reporting</a>, <a href="/settlement.md">Settlement</a></td><td>Documented the <a href="/payments/rebate-program.md">Rebate Program</a>: added Rebate Program under <a href="/payments.md">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="/entity-management/merchant-management/update-merchant.md">Update Merchant's</a> <code>setRebateProgramEnabled</code> change, and partner distribution behavior. Added <a href="/reporting/rebate-reports.md">Rebate Reports</a> under Reporting, documenting the rebate transaction report and the rebate distribution summary (base, period, and account views). Replaced the "<a href="/upcoming-changes/consumer-fee-control-and-exact-net-settlement.md">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="/payments/create-payment.md">Create Payment</a>, <a href="/settlement/settlements.md">Settlements</a>, <a href="/settlement/batches.md">Batches</a>, and <a href="/settlement/residual-reporting.md">Residual Reporting</a> to document rebate-related request fields, response fields, and reporting caveats. Updated <a href="/entity-management/merchant-management/get-merchant.md">Get Merchant</a> to document <code>isRebateProgramEnabled</code>. Expanded <a href="/entity-management/merchant-management/update-merchant.md">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="/reference-guide.md">Reference Guide</a>, <a href="/entity-management.md">Entity Management</a>, <a href="/faqs-and-troubleshooting.md">FAQs</a></td><td>Corrected webhook signature documentation to match live system behavior. Updated <a href="/entity-management/terminal-management/webhook-management.md">Webhook Management</a>, <a href="/reference-guide/operational-guides/webhook-event-reference.md">Webhook Event Reference</a>, and <a href="/faqs-and-troubleshooting/webhooks-and-error-codes/can-i-send-webhook-events-to-multiple-urls.md">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="/faqs-and-troubleshooting/webhooks-and-error-codes/why-is-x-webhook-signature-missing-from-some-webhook-deliveries.md">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="/onboarding.md">Onboarding</a>, <a href="/entity-management.md">Entity Management</a></td><td>Added "Get a partner's fee schedule" to <a href="/entity-management/partner-management.md">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="/onboarding/fee-configuration-for-onboarding-applications.md">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="/onboarding/field-validation-rules.md">Field Validation Rules</a> under Pricing and tenders, and cross-linked the new endpoint from <a href="/reference-guide/operational-guides/merchant-onboarding-guide.md">Merchant Onboarding Guide</a>.</td></tr><tr><td>2026-09-01</td><td><a href="/onboarding.md">Onboarding</a>, <a href="/faqs-and-troubleshooting.md">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="/onboarding/submit-application.md">Submit Application</a> and <a href="/faqs-and-troubleshooting/webhooks-and-error-codes/how-do-i-resolve-a-400-validationerror.md">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="/onboarding/field-validation-rules.md">Field Validation Rules</a> and flagged the exception on <a href="/reference-guide/core-concepts/error-codes.md">Error Codes</a>.</td></tr><tr><td>2026-08-28</td><td><a href="/faqs-and-troubleshooting.md">FAQs</a></td><td>Venmo testing is no longer available. Updated guidance accordingly on <a href="/testing/test-with-venmo.md">Test with Venmo</a>, <a href="/testing.md">Testing</a>, and <a href="/testing/test-with-klarna-recommended.md">Test with Klarna (recommended)</a>.</td></tr><tr><td>2026-08-28</td><td><a href="/entity-management.md">Entity Management</a></td><td>Corrected <code>locationBusinessType</code> irreversibility language on <a href="/onboarding/submit-application.md">Submit Application</a> and <a href="/entity-management/location-management.md">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="/onboarding/cancel-application.md">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="/faqs-and-troubleshooting/entity-management-faqs/can-i-delete-test-or-submitted-applications.md">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="/onboarding.md">Onboarding</a>, <a href="/entity-management.md">Entity Management</a></td><td>Added "What boarding creates" to <a href="/entity-management/location-management.md">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="/reference-guide/operational-guides/merchant-onboarding-guide.md">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="/onboarding.md">Onboarding</a></td><td>Updated <a href="/onboarding/get-status.md">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="/faqs-and-troubleshooting.md">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="/faqs-and-troubleshooting/webhooks-and-error-codes/how-do-i-verify-that-a-webhook-really-came-from-bead.md">How do I verify that a webhook really came from Bead?</a> alongside the existing signature schemes, and added allowlisting guidance on <a href="/faqs-and-troubleshooting/webhooks-and-error-codes/firewall-and-ip-allowlisting-for-webhooks.md">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="/reference-guide.md">Reference Guide</a>, <a href="/entity-management.md">Entity Management</a></td><td>Added <a href="/reference-guide/payment-flows/reading-tender-availability-at-runtime.md">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="/entity-management/terminal-management/managing-tender-types.md">Managing Tender Types</a> and <a href="/reference-guide/payment-flows/choosing-tender-types-by-payment-environment.md">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="/payments.md">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="/settlement.md">Settlement</a>, <a href="/faqs-and-troubleshooting.md">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="/reporting.md">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="/onboarding.md">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="/onboarding.md">Onboarding</a></td><td>Added <a href="/onboarding/list-applications.md">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="/onboarding.md">Onboarding</a> and the <a href="/reference-guide/endpoint-index/table-view-all-apis.md">Reference Guide Endpoint Index</a> to reflect the deprecation and the endpoint's correct location under Partners. Refreshed <a href="/onboarding/get-status.md">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="/settlement.md">Settlement</a></td><td>Updated <a href="/settlement/settlement-reconciliation-patterns.md">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="/entity-management.md">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="/entity-management/terminal-management/create-terminal.md">Create Terminal</a>, <a href="/entity-management/terminal-management/update-terminal.md">Update Terminal</a>, <a href="/faqs-and-troubleshooting/environment-and-testing/how-to-prepare-for-usdc-testing.md">How to Prepare for USDC Testing</a>, and <a href="/faqs-and-troubleshooting/payments-faqs/troubleshooting-couldnt-create-payment-error.md">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="/payments.md">Payments</a></td><td>Added guidance on the <code>conversions</code> array on the <a href="/payments/receipts.md">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="/settlement.md">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="/settlement/payment-settlement-detail.md">Payment Settlement Detail</a> to document the go-forward approach for connecting payments to settlement activity. Updated <a href="/settlement.md">Settlement</a>, <a href="/settlement/settlements.md">Settlements</a>, <a href="/settlement/batches.md">Batches</a>, and <a href="/settlement/deposits.md">Deposits</a> to remove stale cross-references and reflect current endpoints.</td></tr><tr><td>2026-07-01</td><td><a href="/entity-management.md">Entity Management</a></td><td>Added <a href="/entity-management/merchant-management/update-merchant.md">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="/payments.md">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="/settlement.md">Settlement</a></td><td>Added <a href="/settlement/testing-settlement-in-the-test-environment.md">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="/settlement/settlements.md">Settlements</a>, <a href="broken://pages/zKSBYYX80HC72lJTvqVi">Merchant Settlements</a>, and <a href="broken://pages/0I8XtK4ztAK8gab9XUjz">Payment Settlements</a> to align with current API schema.</td></tr><tr><td>2026-06-18</td><td><a href="/reference-guide.md">Reference Guide</a>, <a href="/faqs-and-troubleshooting.md">FAQs</a></td><td>Corrected webhook signature documentation to match live system behavior. Updated <code>x-webhook-signature</code> header format across <a href="/reference-guide/operational-guides/webhook-event-reference.md">Webhook Event Reference</a>, <a href="/entity-management/terminal-management/webhook-management.md">Webhook Management</a>, and <a href="/faqs-and-troubleshooting/webhooks-and-error-codes/how-do-i-verify-that-a-webhook-really-came-from-bead.md">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="/settlement.md">Settlement</a>, <a href="/reporting.md">Reporting</a></td><td>Added <a href="/settlement/residual-reporting.md">Residual Reporting</a> and <a href="/settlement/settlements.md">Settlements</a> to support partner fee revenue reporting. Expanded field-level documentation and corrected enum values across the Settlement section. Updated <a href="/reporting.md">Reporting</a> and <a href="/reporting/payment-history-concepts/pagination-and-sorting.md">Pagination and Sorting</a> with corrected query parameter names and additional filter options.</td></tr><tr><td>2026-06-01</td><td><a href="/payments.md">Payments</a>, <a href="/faqs-and-troubleshooting.md">FAQs</a></td><td>Added <a href="/reference-guide/payment-scenarios/refunds-for-crypto-and-wallet-payments.md">Refunds for Crypto and Wallet Payments</a> to <a href="/reference-guide/payment-scenarios.md">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="/faqs-and-troubleshooting/payments-faqs/does-bead-support-a-refund-api-for-crypto-wallet-and-bnpl-payments.md">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="/payments.md">Payments</a>, <a href="/reference-guide.md">Reference Guide</a>, <a href="/faqs-and-troubleshooting.md">FAQs</a></td><td>Added <a href="/faqs-and-troubleshooting/payments-faqs/why-do-btc-on-chain-payments-take-longer.md">Why do BTC Classic payments take longer?</a> and <a href="/reference-guide/payment-flows/choosing-tender-types-by-payment-environment.md">Choosing Tender Types by Payment Environment</a>. Refreshed <a href="/payments/payment-statuses.md">Payment Statuses</a>, <a href="/payments/create-payment.md">Create Payment</a>, <a href="/payments/crypto-wallet-flow-and-amounts.md">Crypto Wallet Flow and Amounts</a>, <a href="/payments/payment-webhooks.md">Payment Webhooks</a>, <a href="/reference-guide/enumerations-and-schemas/tender-types.md">Tender Types</a>, and <a href="/reference-guide/payment-flows.md">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="/onboarding.md">Onboarding</a></td><td>Added <a href="/onboarding/application-attachments.md">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="/payments.md">Payments</a>,<br><a href="/reference-guide.md">Reference Guide</a>,<br><a href="/faqs-and-troubleshooting.md">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="/payments/create-payment.md">Create Payment</a>, <a href="/quick-start.md">Quick Start</a>, <a href="/payments.md">Payments</a>, <a href="/payments/test-crypto-transactions.md">Test Crypto Transactions</a>, <a href="/faqs-and-troubleshooting/environment-and-testing/crypto-payments-environment-and-testing.md">Crypto payments environment and testing</a>, <a href="/faqs-and-troubleshooting/payments-faqs/crypto-testing-and-fees.md">Crypto Testing and Fees</a>, <a href="/reference-guide/enumerations-and-schemas/tender-types/crypto.md">Crypto Tender Types</a> and <a href="/reference-guide/operational-guides/compatible-crypto-wallets.md">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="/payments.md">Payments</a></td><td>Updated <a href="/payments/create-payment.md">Create Payment</a>, <a href="/payments.md">Payments</a>, and <a href="/reference-guide/enumerations-and-schemas/tender-types.md">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="/onboarding.md">Onboarding</a></td><td>Updated the Onboarding documentation set to align merchant onboarding request guidance with the current API schema. Refreshed <a href="/onboarding/submit-application.md">Submit Application</a>, <a href="/onboarding/sample-payload.md">Sample Payload</a>, and <a href="/onboarding.md">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="/onboarding.md">Onboarding</a></td><td>Added <a href="/onboarding/fee-configuration-for-onboarding-applications.md">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="/reference-guide.md">Reference Guide</a></td><td>Updated <a href="/reference-guide/payment-scenarios.md">Payment Scenarios</a> and <a href="/reference-guide/operational-guides.md">Operational Guides</a> to better separate payment outcome handling from supplemental operational guidance. Added <a href="broken://pages/tww8bW3XqcNID1T5P49a">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="/entity-management.md">Entity Management</a></td><td>Refreshed <a href="/entity-management/terminal-management.md">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="/entity-management.md">Entity Management</a></td><td>Updated <a href="/entity-management/terminal-management/create-terminal.md">Create Terminal</a>, <a href="/entity-management/terminal-management/list-terminals.md">List Terminals</a>, <a href="/entity-management/terminal-management/get-terminal.md">Get Terminal</a>, <a href="/entity-management/terminal-management/update-terminal.md">Update Terminal</a>, <a href="/entity-management/terminal-management/delete-terminal.md">Delete Terminal</a>, and <a href="/entity-management/terminal-management/webhook-management.md">Webhook Management</a> to align terminal docs with current request and response models.</td></tr><tr><td>2026-04-03</td><td><a href="/entity-management.md">Entity Management</a></td><td>Added <a href="/entity-management/terminal-management/reset-terminal-api-key.md">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="/onboarding.md">Onboarding</a></td><td>Updated <a href="/onboarding/webhooks-for-application-events.md">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="/reference-guide.md">Reference Guide</a></td><td>Updated <a href="/reference-guide.md">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="/reference-guide.md">Reference Guide</a></td><td>Updated <a href="/reference-guide/endpoint-index/download-openapi.md">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="/onboarding.md">Onboarding</a></td><td>Refreshed <a href="/onboarding.md">Onboarding</a>, <a href="/onboarding/submit-application.md">Submit Application</a>, and <a href="/onboarding/sample-payload.md">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="/onboarding/test-the-full-onboarding-workflow-in-sandbox.md">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="/reference-guide.md">Reference Guide</a></td><td>Reworked <a href="/reference-guide/enumerations-and-schemas/merchant-onboarding-schema.md">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="/faqs-and-troubleshooting.md">FAQs</a></td><td>Clarified <a href="/faqs-and-troubleshooting/environment-and-testing/sandbox-and-production-urls.md">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="/authentication.md">Authentication</a></td><td>Revised <a href="/authentication.md">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="/introduction.md">Introduction</a></td><td>Aligned <a href="/introduction.md">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="/onboarding.md">Onboarding</a></td><td>Added a new page: <a href="/onboarding/test-the-full-onboarding-workflow-in-sandbox.md">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="/reference-guide.md">Reference Guide</a></td><td>Updated <a href="/reference-guide/operational-guides/webhook-event-reference.md">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="/payments.md">Payments</a></td><td>Updated <a href="/payments/payment-webhooks.md">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="/payments.md">Payments</a><br><a href="/reference-guide.md">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="/payments.md">Payments</a></td><td>Updated the <a href="/payments.md">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="/payments/payment-statuses.md">Payment Statuses</a> to emphasize operational status handling and reclaim scenarios, and updated <a href="/payments/payment-webhooks.md">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="/onboarding.md">Onboarding</a></td><td>Updated <a href="/onboarding/submit-application.md">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="/faqs-and-troubleshooting.md">FAQs</a></td><td>Updated <a href="/faqs-and-troubleshooting/environment-and-testing/how-to-test-klarna-payments.md">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="/faqs-and-troubleshooting.md">FAQs</a></td><td>Updated <a href="/faqs-and-troubleshooting/environment-and-testing/sandbox-and-production-urls.md">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="/onboarding.md">Onboarding</a></td><td>Updated <a href="/onboarding.md">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="/onboarding.md">Onboarding</a></td><td>Refreshed <a href="/onboarding/get-status.md">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="/onboarding.md">Onboarding</a></td><td>Updated <a href="/onboarding/resend-application.md">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="/introduction.md">Introduction</a></td><td>Clarified <a href="/introduction.md">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="/authentication.md">Authentication</a></td><td>Updated <a href="/faqs-and-troubleshooting/authentication-faqs.md">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="/entity-management.md">Entity Management</a></td><td>Refreshed <a href="/entity-management.md">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="/entity-management/terminal-management.md">Terminal Management</a></td><td>Updated <a href="/entity-management/terminal-management.md">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="/onboarding.md">Onboarding</a></td><td>Updated <a href="/onboarding/webhooks-for-application-events.md">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="/faqs-and-troubleshooting.md">FAQs</a></td><td>Added <a href="/faqs-and-troubleshooting/payments-faqs/can-i-view-payments-with-a-payment-api-key.md">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="/payments.md">Payments</a></td><td>Added a new page: <a href="/payments/crypto-wallet-flow-and-amounts.md">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="/reference-guide.md">Reference Guide</a></td><td>Added <a href="/reference-guide/conventions/identifiers-and-keys.md">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="/onboarding.md">Onboarding</a></td><td>Updated the <a href="/onboarding/submit-application.md">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="/payments.md">Payments</a></td><td>Added a new Payments documentation page: <a href="/payments/receipts.md">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="/payments.md">Payments</a></td><td>Updated <a href="/payments.md">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="/reference-guide.md">Reference Guide</a></td><td>Updated <a href="/reference-guide/payment-scenarios.md">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="/quick-start.md">Quick Start</a></td><td>Updated <a href="/quick-start.md">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="/faqs-and-troubleshooting.md">FAQs</a></td><td>Added <a href="/faqs-and-troubleshooting/environment-and-testing/test-data-uniqueness-requirements.md">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="/faqs-and-troubleshooting.md">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="/faqs-and-troubleshooting/entity-management-faqs/can-i-delete-test-or-submitted-applications.md">Can I delete test or submitted applications?</a></td></tr><tr><td>2026-01-19</td><td><a href="/reference-guide.md">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="/onboarding.md">Onboarding</a></td><td>Clarified required fields for minimal onboarding applications and updated the <a href="/onboarding/sample-payload.md">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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.