Sandbox and production URLs

Sandbox and production URLs

Use these values to switch between Sandbox (test) and Production without code changes. The key idea is to keep your base URLs, realms, and credentials in configuration, then load the correct set per environment.

Bead uses different authentication methods depending on the API family:

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

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

Sandbox values (Test / Non prod)

Payments

• Payments API base URL: https://api.test.devs.beadpay.io

• Auth method: X-Api-Key: {apiKey}

OAuth token URL (non Payments APIs and legacy Payments)

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

• Realm: nonprod

Production values

Payments

• Payments API base URL: https://api.devs.beadpay.io

• Auth method: X-Api-Key: {apiKey}

OAuth token URL (non Payments APIs and legacy Payments)

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

• Realm: prod

Note: Always use Production credentials and Production IDs in Production.

Recommended configuration approach

Keep these values in environment variables or secrets, and select them at runtime based on your deployment environment.

Example environment variables:

• BEAD_PAYMENTS_BASE_URL

• BEAD_IDENTITY_TOKEN_URL

• BEAD_REALM

• BEAD_TERMINAL_API_KEY

• BEAD_MERCHANT_ID

• BEAD_TERMINAL_ID

Production switch checklist

If you are using Payments (preferred)

1. Switch Payments base URL from Sandbox to Production.

2. Use your Production apiKey, merchantId, and terminalId.

3. Keep the same Payments request headers:

   • X-Api-Key: {apiKey}

   • Content-Type: application/json

If you are using OAuth APIs (Onboarding, Entity Management, Reporting, Settlement)

1. Switch realm from nonprod to prod.

2. Switch token URL to:

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

3. Use your Production OAuth client credentials and user credentials.

4. Keep the same OAuth request headers:

   • Authorization: Bearer {access_token}

   • Content-Type: application/json

Quick token example (Sandbox)

This is used for OAuth APIs (and legacy Payments integrations).

curl -s -X POST "https://identity.beadpay.io/realms/nonprod/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id={client_id}" \
  -d "username={username}" \
  -d "password={password}"

The response includes access_token. Use it as:

Authorization: Bearer {access_token}

Create a minimal payment (Sandbox)

Payments use API key authentication.

curl -s -X POST "https://api.test.devs.beadpay.io/payments/crypto" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {apiKey}" \
  -d '{
    "merchantId": "{merchantId}",
    "terminalId": "{terminalId}",
    "requestedAmount": 1.00,
    "paymentUrlType": "web",
    "reference": "ORDER-123"
  }'

Use the returned paymentUrls[0] to launch the hosted payment page.

Check payment status by trackingId (Sandbox)

The tracking endpoint uses the same API key approach as POST /payments/crypto.

curl -s -X GET "https://api.test.devs.beadpay.io/payments/tracking/{trackingId}" \
  -H "X-Api-Key: {apiKey}" \
  -H "Accept: application/json"

Verify you are in the right environment

Use these checks when you see unexpected 401 or 403 errors right after switching environments.

What to check

• Payments base URL is correct

  • Sandbox: api.test.devs.beadpay.io

  • Production: api.devs.beadpay.io

• Token URL realm is correct (OAuth APIs)

  • Sandbox: /realms/nonprod/

  • Production: /realms/prod/

• Credentials match the environment

  • Sandbox apiKey, merchantId, terminalId only work in Sandbox

  • Production apiKey, merchantId, terminalId only work in Production

• Do not mix identifiers across environments A Production merchantId used with the Sandbox base URL (or vice versa) commonly results in 401 or 403.

Quick interpretation of common errors

• 401 Unauthorized (Payments) API key is missing, invalid, or the header name is wrong. Header must be exactly X-Api-Key.

• 401 Unauthorized (OAuth APIs) Access token is missing, expired, or the realm and credentials are mismatched.

• 403 Forbidden (Payments) Request is authenticated, but the apiKey is not permitted for the merchantId or terminalId you sent, or you are mixing environments.