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	Download OpenAPI
Endpoint Index	This page, 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 model	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

* Only for endpoint families that explicitly require OAuth.

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.

• Keep Sandbox and Production credentials separate.

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	API key	X-Api-Key: {apiKey}	Use API key authentication for onboarding requests.
Entity Management and related admin/entity operations	API key	X-Api-Key: {apiKey}	Use API key authentication where the product-area docs show X-Api-Key.
Endpoint families that explicitly require OAuth	OAuth 2.0	Authorization: Bearer {access_token}	Only use OAuth where the endpoint family or product-area page explicitly says so.

Standard headers

Use these headers unless an endpoint states otherwise.

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

API key example headers

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

Example curl

curl -s -X GET "https://api.test.devs.beadpay.io/merchant-onboarding/applications/{applicationId}" \
  -H "Accept: application/json" \
  -H "X-Api-Key: {apiKey}"

OAuth guidance

Some Bead endpoint families may still require OAuth. When OAuth applies, follow the authentication instructions on that specific product-area or endpoint-family page.

Token endpoint format

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

Standard OAuth request header

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

Bearer token header

Authorization: Bearer {access_token}

Important note

Do not assume OAuth is required for every Bead API. Use the authentication method documented for the product area you are integrating with.

Conventions

Shared rules for timestamps, identifiers, pagination, errors, and discovery.

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	Treat IDs as opaque strings
Case sensitivity	Enum values and IDs are case sensitive
Immutability	IDs and server-managed timestamps are read-only unless an endpoint explicitly says otherwise

Pagination

Many list endpoints use page and pageSize.

Parameter	Type	Notes
page	integer	Follow the numbering and defaults documented on the specific endpoint
pageSize	integer	Page size

Pagination notes

• Some endpoints return paginated envelopes.

• Some list endpoints return a bare array when the full set is expected to be small.

• Always follow the specific endpoint schema and examples for paging behavior.

Error model

Error responses follow the schema documented for the endpoint or API family.

General guidance:

• Surface the human-readable message to end users when appropriate.

• Log trace or correlation identifiers when present.

• Preserve field-level validation details when available.

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 request shape
401	Missing or invalid credential
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 unless an endpoint explicitly documents otherwise
Precision	Follow the precision documented for the field or tender
Currency	If a field requires a currency, it is documented next to that field; otherwise it may be implied by the merchant, rail, or tender

Tender types and enums

Topic	Convention
Tender types	Use the exact strings shown on the Tender Types pages
Case and separators	Values are case sensitive. Copy them exactly as shown
Future expansion	New enum values can appear without a version change. Ignore unknown values when safe to do so

Rate limits and retries

Topic	Guidance
Retries	Use exponential backoff on 429 and transient 5xx responses
Headers	Respect any retry, quota, or remaining-limit headers if returned
Idempotency	If an endpoint supports idempotency keys, that endpoint page will note it

Download OpenAPI

Use the download page to retrieve the latest OpenAPI specification in JSON format.

The OpenAPI file is useful for:

• generating clients

• validating requests and responses

• aligning internal tooling with the current public schema

• reviewing available paths, request bodies, and response models

Discovery and next steps

Action	Where
Explore paths and methods	Reference Guide, Endpoint Index
Download the OpenAPI specification	Download OpenAPI
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