Environments & Base URLs

Environments & Base URLs

Use the matrix below to target the correct services for your environment. Values shown are the currently active endpoints.

Area	Test / Non-prod	Production
Payment Service API base URL	https://api.test.devs.beadpay.io	Provided during onboarding
OIDC / Identity base	https://identity.beadpay.io/realms/nonprod	https://identity.beadpay.io/realms/prod

Realms

Environment	Realm
Test / Non-prod	nonprod
Production	prod

Token endpoint pattern used for all realms

{OIDC_BASE}/protocol/openid-connect/token

Explicit token URLs

• Test https://identity.beadpay.io/realms/nonprod/protocol/openid-connect/token

• Production https://identity.beadpay.io/realms/prod/protocol/openid-connect/token

Authentication

Resource Owner Password Credentials for terminals

Terminals authenticate with the ROPC flow to obtain an access token using the terminal-issued username and password.

Token URL Test / Non-prod https://identity.beadpay.io/realms/nonprod/protocol/openid-connect/token

Token URL Production https://identity.beadpay.io/realms/prod/protocol/openid-connect/token

Form fields

Field	Value
grant_type	password
client_id	bead-terminal
username	{TERMINAL_ID}@beadpay.io
password	{TERMINAL_PASSWORD}
scope	openid profile email

cURL example Test / Non-prod

curl -sS -X POST \
  https://identity.beadpay.io/realms/nonprod/protocol/openid-connect/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=password' \
  --data 'client_id=bead-terminal' \
  --data 'username=[e-mail]' \
  --data 'password=YOUR_TERMINAL_PASSWORD' \
  --data 'scope=openid profile email'

cURL example Production

curl -sS -X POST \
  https://identity.beadpay.io/realms/prod/protocol/openid-connect/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=password' \
  --data 'client_id=bead-terminal' \
  --data 'username=[e-mail]' \
  --data 'password=YOUR_TERMINAL_PASSWORD' \
  --data 'scope=openid profile email'

Partners using server-to-server integrations can use their assigned OIDC client and flow. Coordinate with your Bead contact to enable.

Using the API

Include these headers on every request

Header	Example
Authorization	Bearer {access_token}
Content-Type	application/json

New Payments integrations authenticate with X-Api-Key: {apiKey} instead of a bearer token. See Authentication.

Example Create a payment in Test / Non-prod

POST https://api.test.devs.beadpay.io/Payments
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "terminalId": "YOUR_TERMINAL_ID",
  "merchantId": "YOUR_MERCHANT_ID",
  "requestedAmount": 100.00,
  "reference": "ORDER123",
  "redirectUrl": "https://yourwebsite.com/payment-success"
}

POST /Payments/crypto is deprecated but still supported and accepts the same request body. Use POST /Payments for new work.

The response includes a paymentId and a paymentUrls array with the hosted payment page URL to redirect the buyer to. It also includes trackingId, a legacy identifier kept for backward compatibility. Use paymentId for status checks.

Polling payment status

Retrieve the current payment status by paymentId

GET {API_BASE}/Payments/{paymentId}/tracking

This endpoint returns the current payment status payload.

trackingId is a legacy identifier. The older endpoint GET {API_BASE}/Payments/tracking/{trackingId} is deprecated but still supported for backward compatibility. New integrations should use paymentId.

Quick Reference

Item	Value
Test Payment API	https://api.test.devs.beadpay.io
OIDC Test base	https://identity.beadpay.io/realms/nonprod
OIDC Production base	https://identity.beadpay.io/realms/prod
Token path	/protocol/openid-connect/token
Common auth client	bead-terminal for terminals