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 '[email protected]' \
  --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 '[email protected]' \
  --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

Example Create a crypto payment in Test / Non-prod

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

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

The response includes a trackingId and a paymentUrls.url to redirect the buyer.

Polling payment status

Retrieve details by tracking id

GET {API_BASE}/Payments/tracking/{trackingId}

This endpoint returns the current payment object.

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