Changelog
2026 Q2 Changelog
2026-07-01
Removed the Merchant Settlements and Payment Settlements pages. The /MerchantSettlements/ endpoints documented on those pages are deprecated and return empty results. Merchant settlement history is now available via GET /Merchants/{merchantId}/settlements. Payment-level settlement context is accessible through settlement fields (settlementId, batchId, batchPeriod, batchStatus) on the PaymentResponse and the batch path via GET /Settlements/{id}/batches. Added Payment Settlement Detail to document the go-forward approach for connecting payments to settlement activity. Updated Settlement, Settlements, Batches, and Deposits to remove stale cross-references and reflect current endpoints.
2026-07-01
Added Update Merchant 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.
2026-06-24
Updated Test Crypto Transactions page content and added Lightning test payment guidance.
2026-06-24
Added Testing Settlement in the Test Environment 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 Settlements, Merchant Settlements, and Payment Settlements to align with current API schema.
2026-06-18
Corrected webhook signature documentation to match live system behavior. Updated x-webhook-signature header format across Webhook Event Reference, Webhook Management, and How do I verify that a webhook really came from Bead? to reflect that t is a Unix epoch timestamp in milliseconds (not seconds) and s is a Base64-encoded HMAC-SHA256 digest (not hex). Updated the Node.js verification code example to use .digest("base64") and millisecond-based timestamp comparison. Corrected the PUT /Terminals/{id}/webhook request body field from webhookUrl to url and authentication header from OAuth Bearer to X-Api-Key. Replaced placeholder signingSecret example values with accurate format. Added explicit guidance that x-webhook-signature is present on terminal-level webhook deliveries only and is not included on per-payment webhookUrls deliveries.
2026-06-09
Added Residual Reporting and Settlements to support partner fee revenue reporting. Expanded field-level documentation and corrected enum values across the Settlement section. Updated Reporting and Pagination and Sorting with corrected query parameter names and additional filter options.
2026-06-01
Added Refunds for Crypto and Wallet Payments to Payment Scenarios 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 fullyRefunded and partiallyRefunded are reserved and not currently returned, with a link to the new refund guidance. Added Does Bead support a refund API for crypto, wallet, and BNPL payments? to Payments FAQs.
2026-05-21
Added Why do BTC Classic payments take longer? and Choosing Tender Types by Payment Environment. Refreshed Payment Statuses, Create Payment, Crypto Wallet Flow and Amounts, Payment Webhooks, Tender Types, and Payment Flows to clarify BTC Classic / Bitcoin on-chain timing, processing versus completed handling, asynchronous customer experiences, webhook-driven completion, and fulfillment guidance for physical, digital, invoice, and delayed-delivery environments.
2026-05-06
Added Application Attachments 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.
2026-04-27
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 Create Payment, Quick Start, Payments, Test Crypto Transactions, Crypto payments environment and testing, Crypto Testing and Fees, Crypto Tender Types and Compatible Crypto Wallets. Cleaned up stale testnet-oriented USDC guidance and aligned tender references for USDC on Base, USDC on Solana, Bitcoin on chain, and Bitcoin Lightning.
2026-04-21
Updated Create Payment, Payments, and Tender Types to clarify optional tender preselection on the hosted payment page, including default tender selection when tenderTypes is omitted and how tenderTypes can be used to preselect or constrain the hosted experience.
2026-04-10
Updated the Onboarding documentation set to align merchant onboarding request guidance with the current API schema. Refreshed Submit Application, Sample Payload, and Onboarding to reflect the current full and short application patterns, including signer placement in merchantData.stakeholders for full applications and signerFirstName, signerLastName, and signerEmail for short applications, while preserving practical implementation guidance and current response examples.
2026-04-07
Added Fee Configuration for Onboarding Applications and refreshed related onboarding examples to align feeInformation, cryptoEnvironment, 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.
2026-04-07
Updated Payment Scenarios and Operational Guides to better separate payment outcome handling from supplemental operational guidance. Added Refunds for Crypto and Wallet Payments and refreshed underpaid, overpaid, reclaim, and section-level navigation guidance to align with current supported behavior.
2026-04-03
Refreshed Terminal Management authentication and lifecycle guidance to use admin API key headers for terminal-management operations and terminal payments API keys for payment activity.
2026-04-03
Updated Create Terminal, List Terminals, Get Terminal, Update Terminal, Delete Terminal, and Webhook Management to align terminal docs with current request and response models.
2026-04-03
Added Reset Terminal API Key to document terminal credential rotation and secure storage of the returned payments API key.
2026-04-01
Updated Webhooks for Application Events to align onboarding webhook documentation with the current API, including X-Api-Key authentication, POST /merchant-onboarding/{partnerId}/webhook registration, returned webhookSecret handling, supported onboarding event types, and clearer guidance for verification, idempotent processing, follow-up status lookups, and webhook removal.
2026-04-01
Updated Reference Guide to align shared authentication guidance with current documentation, clarify that onboarding and related admin or entity-management flows use X-Api-Key where documented, limit OAuth guidance to endpoint families that explicitly require it, and remove Postman-specific references from shared guidance.
2026-04-01
Updated Download OpenAPI 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.
2026 Q1 Changelog
2026-03-31
Refreshed Onboarding, Submit Application, and Sample Payload to align merchant onboarding guidance with the current API, including the plural application endpoints, the current full (signer + merchantData) and minimal (signerName / signerEmail) request shapes, required cryptoEnvironment usage for Sandbox versus Production, and the addition of Test the Full Onboarding Workflow in Sandbox for end-to-end testing guidance.
2026-03-31
Reworked Merchant Onboarding Schema to reflect the current onboarding create models, including the plural application endpoints, current full and minimal request shapes, required cryptoEnvironment values, updated fee structures, and current create response fields.
2026-03-31
Clarified Sandbox and production URLs with environment-specific onboarding guidance, including API-key-based onboarding authentication, the required cryptoEnvironment field for onboarding create requests, and how to align Sandbox versus Production credentials and request values.
2026-03-31
Revised Authentication 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 cryptoEnvironment as required for onboarding create requests.
2026-03-31
Aligned Introduction 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 cryptoEnvironment setting for onboarding create requests.
2026-03-31
Added a new page: Test the Full Onboarding Workflow in Sandbox. 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.
2026-03-30
Updated Webhook Event Reference 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.
2026-03-30
Updated Payment Webhooks to include a concrete webhook payload example, field-by-field documentation, clearer guidance on using trackingId for correlation and follow-up status lookups, and stronger implementation guidance for signature verification, idempotent processing, and duplicate delivery handling.
2026-03-12
Updated to remove paymentUrlType references. This field is optional and not used, so this is a documentation cleanup only and does not introduce breaking behavior for existing integrations.
2026-03-07
Updated the Payments documentation set to align authentication and endpoint guidance across overview and workflow pages. Clarified that new Payments integrations use X-Api-Key, preserved legacy OAuth guidance only where applicable, corrected Payments endpoint references to POST /Payments/crypto, added clearer request guidance for terminals with type = virtual versus type = physical, refined Payment Statuses to emphasize operational status handling and reclaim scenarios, and updated Payment Webhooks to reinforce webhook-first event handling and terminal webhook configuration using the supported methods.
2026-03-07
Updated Submit Application to use the plural onboarding endpoints, align request guidance to signerInfo, 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.
2026-03-07
Updated How to Test Klarna Payments to use X-Api-Key header authentication, corrected Payments endpoint references to POST /Payments/crypto, and clarified Klarna request requirements by terminal type, including different minimum fields for virtual versus physical terminals.
2026-03-07
Updated Sandbox and production URLs 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 POST /Payments/crypto, and note that payment request field requirements can vary by terminal configuration and tender flow.
2026-03-07
Updated Onboarding to use the plural application endpoints, align onboarding terminology to signerInfo, 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.
2026-03-07
Refreshed Get Status to focus on the most important operational response fields such as id, merchantName, status, and onboardedMerchantId, align endpoint references to the plural onboarding paths, and remove unnecessary nested response detail in favor of the spec for full schema coverage.
2026-03-07
Updated Resend Application 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.
2026-03-06
Clarified Introduction authentication guidance across API families, aligned onboarding terminology to signerInfo, and noted that API-initiated onboarding emails the merchant signer a secure link.
2026-03-06
Updated Authentication to distinguish API key versus OAuth usage, added onboarding API key guidance, and corrected Payments endpoint references to POST /Payments/crypto.
2026-03-06
Refreshed Entity Management to better describe API purpose, align onboarding wording to signerInfo, and clarify authentication guidance for onboarding versus other flows.
2026-03-06
Updated Terminal Management to correct the terminal update method to PUT /Terminals/{id} and clarify terminal lifecycle guidance, including update, disable, and delete behavior.
2026-02-27
Updated Webhooks for Application Events 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.
2026-02-27
Added Can I view payments with a Payment API key? FAQ page with a terminalId-based payment history example (GET /Payments), plus pagination basics and a link to Pagination and sorting.
2026-02-23
Added a new page: Crypto Wallet Flow and Amounts. 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.
2026-02-20
Added Identifiers and Keys 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.
2026-02-10
Updated the Submit Application 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.
2026-02-10
Added a new Payments documentation page: Receipts. 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 (emailReceipt, smsReceipt).
2026-01-30
Updated Payments documentation to clarify underpaid and overpaid behavior, including recommended integrator handling and reclaim outcomes.
2026-01-30
Updated Payment Scenarios guidance for underpaid, overpaid, and reclaiming unconverted crypto to align with current product behavior and customer reclaim steps.
2026-01-30
Updated Quick Start to include underpayment and overpayment outcomes, reclaim email expectations, and recommended confirmation patterns.
2026-01-27
Added Test Data Guidelines: Email Addresses 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.
2026-01-19
Clarified that applications cannot be deleted once submitted due to compliance requirements. Added guidance on managing test applications. Can I delete test or submitted applications?
2026-01-19
Removed references to client secrets and client credential grant flows from the documentation to reflect the current authentication models in use.
2026-01-19
Clarified required fields for minimal onboarding applications and updated the Sample Payload documentation to include full fee information, reflecting the minimum data needed for applications sent directly to signing.
Last updated