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, automatically email the 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: terminal apiKey, merchantId, terminalId

  • Onboarding and entity workflows: OAuth client details and user credentials

• 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 Create Payment

• 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 (preferred)

  • Use a terminal API key

  • Send X-Api-Key: {apiKey} on Payments requests

• Other Bead APIs (Onboarding, Entity Management, Reporting, Settlement)

  • Use OAuth 2.0 with OpenID Connect

  • Send Authorization: Bearer {access_token}

• Legacy Payments support

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

  • New Payments integrations should use X-Api-Key

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 base URLs and identity realms.

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 identifier (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 call create payment and tracking using X-Api-Key

  • OAuth APIs: 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 to 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 (for example, trackingId, paymentPageId, merchantId, terminalId) and the timestamp of the failing request.

• Do not share secret credentials (apiKey, passwords, access tokens) in tickets or chat.