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.

• Confirm your environment base URLs and identity realm.

• Choose an HTTP client or Postman to make requests.

Pick a path

• Accept a payment

• Submit a merchant application

• Manage entities after approval

Authentication at a glance

• OAuth 2.0 with OpenID Connect.

• Access tokens are required for all API calls.

• See the Authentication section for grant types, token fields, and examples.

Environments

• Sandbox for development and integration testing.

• Production for live traffic after certification.

API conventions

• JSON request and response bodies.

• ISO 8601 timestamps in UTC.

• Idempotency keys on POST operations you may retry.

• Standardized error payloads with type, title, status, and trace identifier.

Webhooks and events

• Optional webhooks allow you to receive status changes without polling.

• Event payloads follow a consistent envelope structure.

Production readiness checklist

• You can authenticate and refresh 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) are registered, verified, and retried successfully.

• Logging and monitoring include request IDs and event IDs.

• Error handling and idempotent retry behavior are implemented.

Support

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

• Include relevant identifiers (for example, a payment or application ID) when opening support requests.