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	Create hosted payment pages, run server-to-server payments, track payment status, and consume payment webhooks
Onboarding	Submit merchant applications by API, send a hosted application to a signer, and track application status through approval
Entity Management	Create and manage merchants, locations, terminals, permissions, and related entities after approval
Settlement & Reporting	Retrieve payment history, batches, settlements, and deposits for reconciliation
Reference Guide	Review shared concepts, schemas, endpoint index, environments, and error behavior
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:

X-Api-Key: {apiKey}

Onboarding API

Onboarding requests use an API key.

Send:

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:

Authorization: Bearer {access_token}

Legacy Payments support

Existing Payments integrations may still use OAuth password grant.

New Payments integrations should use:

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.