Download OpenAPI / Postman

Use these downloads to explore the API and run calls in Postman. The OpenAPI file is machine readable, and the Postman assets include ready to use environments for Sandbox and Production.

Important: Bead uses different authentication methods depending on the API family:

• Payments use a terminal API key sent as X-Api-Key

• Other Bead APIs (Onboarding, Entity Management, Reporting, Settlement) use OAuth 2.0 access tokens

What you can download

Asset	Purpose	Format
OpenAPI v1	Full REST specification for all public endpoints	JSON
Postman Collection	All endpoints with example requests and response bodies	JSON
Postman Environment Sandbox	Variables for Sandbox including base URL and token URL	JSON
Postman Environment Production	Variables for Production including base URL and token URL	JSON

Downloads:

• OpenAPI v1 (JSON): Download

• Postman Collection (JSON): Download

• Postman Environment Sandbox (JSON): Download

• Postman Environment Production (JSON): Download

Tip: If you paste this page into GitBook, reattach the four files above and update the links.

Base URLs used by the assets

Environment	REST API base URL	OAuth token URL
Sandbox	https://api.test.devs.beadpay.io	https://identity.beadpay.io/realms/<realm>/protocol/openid-connect/token
Production	https://api.beadpay.io	https://identity.beadpay.io/realms/<realm>/protocol/openid-connect/token

Note: The token path follows OpenID Connect. Your realm value differs by environment. If you are unsure which realm to use, contact your Bead representative.

Quick start in Postman

1. Download the Postman Collection and the Postman Environment for the environment you plan to use.

2. Import both files into Postman.

3. Select the imported environment as your active environment.

4. Configure authentication based on what you are testing:

   • Payments: set paymentsApiKey and use X-Api-Key: {{paymentsApiKey}}

   • OAuth APIs: request a token and save it as access_token for Authorization: Bearer {{access_token}}

5. Send requests from the collection.

Authentication setup

Payments (preferred): API key

Payments endpoints authenticate with a terminal API key, not OAuth.

• apiKey is the secret credential

• maskedApiKey is not usable

• Send the full apiKey value via X-Api-Key

In Postman:

• Add an environment variable named paymentsApiKey

• On Payments requests, add a header:

  • X-Api-Key: {{paymentsApiKey}}

If your imported collection adds Authorization: Bearer {{access_token}} globally, you can keep it for the OAuth API families. For Payments requests, add the X-Api-Key header at the request or folder level. Payments will ignore OAuth and rely on X-Api-Key.

OAuth APIs: access token

Onboarding, Entity Management, Reporting, and Settlement use OAuth 2.0 access tokens.

In Postman:

• Request a token using your OAuth client details

• Save the returned access token to the environment variable access_token

• Send requests with:

  • Authorization: Bearer {{access_token}}

Environment variables included

These variables are used by the collection. You can add additional variables as needed.

Variable	Description	Example value Sandbox	Example value Production
baseUrl	Host for API requests	https://api.test.devs.beadpay.io	https://api.beadpay.io
tokenUrl	OAuth token endpoint	https://identity.beadpay.io/realms/<realm>/protocol/openid-connect/token	https://identity.beadpay.io/realms/<realm>/protocol/openid-connect/token
clientId	OAuth client identifier assigned to you	your-sandbox-client-id	your-prod-client-id
clientSecret	OAuth client secret	••••••••	••••••••
username	When using password grant	[email protected]	[email protected]
password	When using password grant	••••••••	••••••••
scope	Optional scope string	openid profile email	openid profile email
access_token	OAuth bearer token stored after authentication	set by you	set by you
merchantId	Helpful for Payments examples	mer_4e5a13aa	mer_4e5a13aa
partnerId	Helpful for partner scoped examples	par_12345678	par_12345678
paymentsApiKey	Terminal API key for Payments requests	term.<...>.<...>	term.<...>.<...>
terminalId	Helpful for Payments examples	term_123	term_123

Credential profiles: Many teams use separate credentials for Boarding and for Payments. Create one Postman environment per credential set, or duplicate the environment and update values accordingly.

How to fetch a token (OAuth APIs)

Use your preferred grant type. The example below shows a password grant. Client credentials grant follows the same token URL with grant_type=client_credentials.

Copy the access_token value into your Postman environment variable named access_token.

curl -X POST "{{tokenUrl}}" \
  -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={{scope}}"

Example request using variables

Payments example (API key): create a hosted payment

curl -X POST "{{baseUrl}}/payments/crypto" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {{paymentsApiKey}}" \
  -d '{
    "merchantId": "{{merchantId}}",
    "terminalId": "{{terminalId}}",
    "requestedAmount": 1.00,
    "paymentUrlType": "web",
    "reference": "ORDER-123"
  }'

Health check example

curl -X GET "{{baseUrl}}/health" \
  -H "Accept: application/json"

Versioning and updates

Topic	Guidance
Spec version	OpenAPI v1 is the current public specification
Backward compatibility	Breaking changes are announced on the Changelog and communicated to registered partners
Regeneration	If your code generator requires a local file, re download the OpenAPI file when you see a new date on the Changelog

Troubleshooting

Symptom	Likely cause	Fix
401 on Payments requests	Missing or invalid API key	Confirm X-Api-Key is present and uses {{paymentsApiKey}}
401 on OAuth API requests	Missing or expired token	Refresh the token and confirm the header reads Authorization: Bearer {{access_token}}
403 on a valid credential	Wrong environment, wrong merchant or terminal relationship, or missing permission	Confirm you used the correct environment and credentials for the endpoint
404 on a known endpoint	Wrong base URL	Confirm baseUrl points to the correct environment
Request timeouts	Local firewall or VPN rules	Allow outbound traffic to the base URL and the identity host

Next steps

Action	Where
Review Authentication	Authentication page
Explore methods and paths	Endpoint Index
Set up webhook receivers	Webhook Event Reference
Learn payment scenarios	Payment Scenarios