Reference Guide

This guide sets standards and shared patterns for authentication, headers, pagination, errors, field formats, and discovery. Use it with the Endpoint Index and the product area guides.

Quick links

Topic	Where
Environments and Base URLs	Reference Guide
Download OpenAPI and Postman	Reference Guide
Endpoint Index	Reference Guide
Authentication and OAuth	Reference Guide
Tender Types	Reference Guide
Payment History concepts	Reference Guide
Rate Limits and Throttling	Reference Guide
Error Codes	Reference Guide
Webhook Event Reference	Reference Guide
Entity Management	Locations, Terminals, Partners, Merchants

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
Note Use the correct realm per environment. See Environments and Base URLs for details and retention policy.

Authentication

Use OAuth to obtain an access token, then pass it on every request. Headers

Header	Value
Authorization	Bearer <access_token>
Content Type	application/json for requests with bodies
Accept	application/json
Get a token

curl -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>" \
  -d "scope=openid profile email"

Copy the access_token into your client or Postman environment.

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 other 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.
Name	Type
---	---
page	integer
pageSize	integer
Response envelope
Field	Type
---	---
data	array
total	integer
page	integer
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 users and log traceId.

{
  "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" }
  ]
}

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
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 token
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

Discovery and next steps

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