Reference Guide

This guide defines shared patterns used across Bead APIs, including authentication, headers, pagination, errors, field formats, and discovery. Use it alongside the Endpoint Index and the product area guides.

Quick links

Topic	Where
Environments and Base URLs	This page, Environments at a glance
Download OpenAPI and Postman	Download OpenAPI and Postman
Endpoint Index	Reference Guide, Endpoint Index
Authentication	This page, Authentication at a glance
Tender Types	Payments, Tender Types
Payment History concepts	Reporting, Payment History
Rate limits and retries	This page, Rate limits and retries
Error codes	This page, Error model
Webhook Event Reference	Payments, Webhook Event Reference

Environments at a glance

Environment	Purpose	REST API base URL	OAuth token URL
Sandbox	Functional testing and integration QA	https://api.test.devs.beadpay.io	https://identity.beadpay.io/realms/{realm}/protocol/openid-connect/token
Production	Live merchant traffic and settlement	https://api.beadpay.io	https://identity.beadpay.io/realms/{realm}/protocol/openid-connect/token

Notes

• Use the correct realm per environment. Your Bead contact will confirm the realm values you should use for Sandbox and Production.

• Keep base URLs and credentials in configuration so switching environments is a deploy time change, not a code change.

Authentication at a glance

Bead supports multiple authentication methods depending on the API family you are calling.

API family	Preferred auth	Required header	Notes
Payments	Terminal API key	X-Api-Key: {apiKey}	Use the full apiKey value. maskedApiKey is not usable.
Onboarding, Entity Management, Settlement, Reporting	OAuth 2.0 (OpenID Connect)	Authorization: Bearer {access_token}	Obtain an access token from the token endpoint, then pass it on API requests.
Payments (legacy support)	OAuth password grant	Authorization: Bearer {access_token}	Supported for existing integrators. New Payments integrations should use API key.

Standard headers

Use these headers unless an endpoint states otherwise.

Header	Value
Content-Type	application/json for requests with JSON bodies
Accept	application/json

Payments example headers (API key)

Header	Value
X-Api-Key	{apiKey}
Content-Type	application/json
Accept	application/json

Example curl

curl -s -X POST "https://api.test.devs.beadpay.io/payments/crypto" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Api-Key: {apiKey}" \
  -d '{
    "merchantId": "{merchantId}",
    "terminalId": "{terminalId}",
    "requestedAmount": 1.00,
    "paymentUrlType": "web",
    "reference": "ORDER-123"
  }'

OAuth token request (OpenID Connect)

Use OAuth for Onboarding, Entity Management, Settlement, and Reporting. Legacy Payments integrations may also use OAuth.

Token endpoint format

POST https://identity.beadpay.io/realms/{realm}/protocol/openid-connect/token

Header

Content-Type: application/x-www-form-urlencoded

Example curl (password grant)

curl -s -X POST "https://identity.beadpay.io/realms/{realm}/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id={clientId}" \
  -d "client_secret={clientSecret}" \
  -d "username={username}" \
  -d "password={password}"

Then pass the access token on requests:

Authorization: Bearer {access_token}

Conventions

Shared rules for pagination, time formats, identifiers, and the error model.

Timestamps

Topic	Convention
Format	ISO 8601 in UTC with Z suffix
Examples	2025-09-02T16:22:11Z, 2025-09-02T16:22:11.015Z
Fields	created, updated, and similar date fields use UTC

Identifiers and casing

Topic	Convention
IDs	Opaque strings such as mer_4e5a13aa, loc_bfdc6a7f, term_123
Case sensitivity	Enum values and IDs are case sensitive
Immutability	IDs and timestamps are read only

Pagination

Paginated endpoints accept page and pageSize and return a standard envelope. One based indexing is used.

Request parameters

Name	Type	Notes
page	integer	One based index
pageSize	integer	Page size

Response envelope

Field	Type	Notes
data	array	Page of results
total	integer	Total matching records
page	integer	Current page

Non paginated lists

• Some list endpoints return a bare array when the full set is expected to be small. In those cases the pagination parameters and envelope are not used.

Error model

All error responses return a consistent JSON object. Surface message to end users and log traceId for support.

Field	Type	Description
code	string	Stable programmatic code such as validation_error, not_found, forbidden
error	string	Short category label used in logs
message	string	Human readable explanation
traceId	string	Correlation identifier for support
details	array	Optional per field errors with field and message

Example error payload

{
  "code": "validation_error",
  "error": "Invalid request",
  "message": "One or more fields are invalid.",
  "traceId": "00-73fffe343fd1d5b150beddb00730bb24-f182c31fd104b782-00",
  "details": [
    { "field": "address.postalCode", "message": "Invalid format" }
  ]
}

HTTP status codes

Status	When
200	Successful read or update
201	Resource created
202	Accepted for asynchronous processing
204	Successful delete with no body
400	Invalid input or immutable field modified
401	Missing or invalid credential (API key or token depending on endpoint)
403	Authenticated but not permitted
404	Resource not found
409	Duplicate or state conflict
422	Business rule failure
500	Unexpected server error

Amounts and currencies

Topic	Convention
Numeric fields	Use JSON numbers, not strings
Precision	Two decimal places unless a field specifies otherwise
Currency	If a field requires a currency it is documented next to that field. Otherwise the currency is implied by the merchant or rail

Tender types and enums

Topic	Convention
Tender types	Use the exact strings shown on the Tender Types pages such as usdcBase, ethereum
Case and separators	Values are case sensitive. Copy them exactly as shown
Future expansion	New enum values can appear without a version change. Unknown values should be ignored when safe

Rate limits and retries

Topic	Guidance
Retries	Use exponential backoff on 429 and transient 5xx
Headers	Some endpoints return remaining quota headers
Idempotency	If an endpoint supports idempotency keys it will note that on its page

Download OpenAPI and Postman

Use the Download OpenAPI and Postman page to retrieve:

• OpenAPI specification (JSON)

• Postman collection (if available)

These assets are useful for generating clients, validating requests, and keeping internal tooling aligned with the latest schema.

Discovery and next steps

Action	Where
Explore paths and methods	Reference Guide, Endpoint Index
Download the OpenAPI and Postman assets	Download OpenAPI and Postman
Review webhook event types and signatures	Payments, Webhook Event Reference
Learn payment history filters and paging	Reporting, Payment History concepts
See changes by area and date	Changelog