# Introduction Welcome to the Bead developer documentation. Use these docs to: * accept payments * submit merchant onboarding applications * manage approved merchants, locations, and terminals * retrieve reporting and settlement data ### What you’ll find here | Area | What you can do | | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | [Payments](https://developers.bead.xyz/payments) | Create hosted payment pages, run server-to-server payments, track payment status, and consume payment webhooks | | [Onboarding](https://developers.bead.xyz/onboarding) | Submit merchant applications by API, send a hosted application to a signer, and track application status through approval | | [Entity Management](https://developers.bead.xyz/entity-management) | Create and manage merchants, locations, terminals, permissions, and related entities after approval | | [Settlement](https://developers.bead.xyz/settlement) & [Reporting](https://developers.bead.xyz/reporting) | Retrieve payment history, batches, settlements, and deposits for reconciliation | | [Reference Guide](https://developers.bead.xyz/reference-guide) | Review shared concepts, schemas, endpoint index, environments, and error behavior | | [Changelog](https://developers.bead.xyz/changelog) | Track developer-facing documentation and API updates | ### Before you begin Make sure you have the right credentials for the API families you plan to use. #### Sandbox credentials * **Payments** * API key * `merchantId` * `terminalId` * **Onboarding** * onboarding API key * **Other Bead APIs** * use the authentication model required by that API family Also confirm: * your environment base URLs * whether you are working in Sandbox or Production * your preferred HTTP client or SDK workflow If you are missing credentials, contact your Bead partner contact. ### Pick a path #### Accept a payment Start with: * Quick Start * Payments #### Submit a merchant application Start with: * Onboarding #### Manage entities after approval Start with: * Entity Management #### Reconcile transactions and funding Start with: * Reporting * Settlement ### Authentication at a glance Bead supports multiple authentication methods depending on the API family. #### Payments API Payments requests use an API key. Send: ```http X-Api-Key: {apiKey} ``` #### Onboarding API Onboarding requests use an API key. Send: ```http X-Api-Key: {apiKey} ``` When onboarding is initiated by API, Bead emails the merchant signer a secure link to complete the hosted onboarding flow. For onboarding create requests: * full application requests use `signer` and `merchantData` * minimal application requests use `signerName` and `signerEmail` * onboarding create requests require `cryptoEnvironment` #### Other Bead APIs Some other Bead APIs may still use OAuth 2.0 with OpenID Connect, depending on the product area and endpoint family. Send: ```http Authorization: Bearer {access_token} ``` #### Legacy Payments support Existing Payments integrations may still use OAuth password grant. New Payments integrations should use: ```http X-Api-Key: {apiKey} ``` #### Guidance * Do not send deprecated onboarding `apiKey` fields in request bodies * Use the request shapes documented on the current onboarding pages * For onboarding create requests, set `cryptoEnvironment` to the environment you are targeting See **Authentication** for detailed examples. ### Environments Bead supports separate environments for development and live traffic. #### Sandbox Use Sandbox for: * development * integration testing * end-to-end onboarding testing * webhook validation #### Production Use Production for: * live merchant traffic * live settlement activity * certified integrations See **Sandbox and production URLs** for current base URLs, token URLs, and onboarding environment rules. ### Important onboarding note Onboarding create requests require `cryptoEnvironment`. Use: * `sandbox` in Sandbox * `production` in Production This applies to both onboarding create flows: * `POST /merchant-onboarding/applications` * `POST /merchant-onboarding/applications-short` ### API conventions Bead APIs generally follow these conventions: * JSON request and response bodies * ISO 8601 timestamps in UTC * standardized error responses for validation and authorization failures * idempotent handling where supported by the endpoint * environment-specific credentials and identifiers ### Webhooks and events Bead supports webhook-driven integrations for event-based workflows. Typical uses include: * payment status updates * onboarding application lifecycle events If you use webhooks: * respond quickly with `2xx` * process events idempotently * log event identifiers for troubleshooting * treat your webhook consumer like a production service ### Production readiness checklist Before going live, confirm the following. #### Authentication * you can authenticate successfully for each API family you use * your Sandbox and Production credentials are stored separately * your code applies the correct auth header for each API family #### Payments * you can create a payment * you can retrieve payment status successfully * your system handles payment lifecycle outcomes correctly #### Onboarding * you can submit an application successfully * you can track application status through approval * your integration sends the correct onboarding request shape * your integration sets `cryptoEnvironment` correctly for the target environment #### Webhooks * webhook endpoints are reachable * webhook events are logged and processed safely * retries do not create duplicate side effects #### Observability * request identifiers and event identifiers are logged * errors are traceable by environment and API family * support-ready context is captured for failed calls #### Resilience * retry behavior is safe * validation errors are surfaced clearly * environment mismatches are easy to diagnose ### Support Use your Bead partner contact for: * credentials * environment questions * onboarding workflow support * certification and production-readiness questions When opening support requests, include relevant identifiers such as: * `trackingId` * `paymentPageId` * `merchantId` * `terminalId` * `applicationId` Include the approximate timestamp of the failing request and the environment used.