Introduction

Welcome to the Bead developer documentation. Use these docs to accept payments, submit merchant applications, and manage approved merchants, locations, and terminals.

What you’ll find here

Area	What you can do
Payments	Create hosted payment pages, run server-to-server payments, track status, and consume webhook events.
Onboarding	Submit a merchant application via API, provide applicant and signerInfo details in the request, automatically email the merchant signer a secure link, and track status through approval.
Entity Management	Add merchants and locations, provision terminals, and manage tender types and permissions.
Settlement & Reporting	Retrieve settlement batches and payment history for reconciliation.
Reference Guide	Core concepts, schemas, endpoint index, error formats, and rate limits.
Changelog	Developer-facing changes found at the category / segment level

Before you begin

• Get sandbox credentials for your team.

  • Payments: API key, merchantId, and terminalId

  • Onboarding: API key for onboarding requests

  • Other Bead APIs: use the authentication model required by that API family

• Confirm your environment base URLs (Sandbox vs Production).

• Choose an HTTP client (curl, Postman, or your own tooling).

If you are missing credentials, contact your Bead partner contact.

Pick a path

• Accept a payment

  • Start with Quick Start and then continue to Payments.

• Submit a merchant application

  • Start with Onboarding

• Manage entities after approval

  • Start with Entity Management

Authentication at a glance

Bead supports multiple authentication methods depending on the API family.

Payments API

• Use an API key for Payments requests

• Send X-Api-Key: {apiKey}

Onboarding API

• Use an API key for onboarding requests

• Send X-Api-Key: {apiKey}

• Follow the current onboarding endpoint documentation and examples for request requirements

• When onboarding is initiated by API, Bead emails the merchant signer a secure link to complete the required signing flow

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 Authorization: Bearer {access_token} where OAuth is required

Legacy Payments support

• Existing integrators may still use the OAuth password grant for Payments

• New Payments integrations should use X-Api-Key

Guidance

• Do not send deprecated apiKey fields in onboarding request bodies

• Use signerInfo where signer details are required

See Authentication for details and examples.

Environments

• Sandbox

  • For development and integration testing

• Production

  • For live traffic after certification

See Sandbox and production URLs for the current base URLs and access requirements.

API conventions

• JSON request and response bodies

• ISO 8601 timestamps in UTC

• Idempotency keys on POST operations you may retry (when supported by the endpoint)

• Standardized error payloads with type, title, status, and trace identifiers when returned

Webhooks and events

• Optional webhooks allow you to receive status changes without polling

• Event payloads follow a consistent envelope structure

If you use webhooks, treat your webhook endpoint like a production service:

• Validate signatures (when available)

• Respond quickly with 200 OK

• Retry safely using event IDs and idempotent processing on your side

Production readiness checklist

• You can authenticate successfully for the API families you use

  • Payments: you can create and track payments using X-Api-Key

  • Onboarding: you can submit merchant applications using X-Api-Key

  • OAuth-based APIs, if applicable: you can obtain and refresh access tokens

• Payments

  • You can create a payment and confirm final status

• Onboarding

  • You can submit an application and track status through approval

• Webhooks (if used)

  • Endpoints are registered, reachable, and retried successfully

• Observability

  • Logging and monitoring include request IDs and event IDs

• Resilience

  • Error handling and retry behavior are implemented safely

Support

• Use your Bead partner contact for credentials, environment questions, and certification.

• When opening support requests, include relevant identifiers such as trackingId, paymentPageId, merchantId, terminalId, or applicationId, along with the timestamp of the failing request.

• Do not share secret credentials such as API keys, passwords, or access tokens in tickets or chat.