# 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. --- # Agent Instructions: 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: ``` GET https://developers.bead.xyz/introduction.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.