Sandbox and production URLs

Use these values to switch between Sandbox and Production without code changes. 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 an API key sent as X-Api-Key.

• Onboarding requests use an API key sent as X-Api-Key.

• Other Bead APIs may use OAuth 2.0 access tokens depending on the product area and endpoint family.

Sandbox values

Payments

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

• Auth method:

X-Api-Key: {apiKey}

OAuth token URL

Use this for OAuth APIs and legacy Payments integrations.

• 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

Use this for OAuth APIs and legacy Payments integrations.

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

• Realm: prod

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

If you also call onboarding APIs, keep that API key in a separate secret or configuration value so Payments and onboarding credentials are managed independently.

Production switch checklist

If you are using Payments

1. Switch the Payments base URL from Sandbox to Production.

2. Use your Production API key, merchantId, and terminalId.

3. Keep the same Payments request headers:

X-Api-Key: {apiKey}
Content-Type: application/json

If you are using onboarding APIs

1. Switch the onboarding base URL and credentials to the Production values for that environment.

2. Use your Production onboarding API key.

3. Keep the same onboarding request header:

X-Api-Key: {apiKey}

If you are using OAuth APIs

1. Switch the realm from nonprod to prod.

2. Switch the token URL to:

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

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

2. 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.

The response includes access_token. Use it as:

Authorization: Bearer {access_token}

Example curl:

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

Create a payment request (Sandbox)

Payments use API key authentication.

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

Required request fields can vary depending on terminal configuration, terminal type, and tender-specific requirements. Always confirm the current requirements for your terminal and payment flow before promoting an example to production use.

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,
    "reference": "ORDER-482"
  }'

Note on required fields

The example above is a basic Payments example, not a universal minimum request body for every payment flow.

Examples:

• some terminal configurations may require additional fields

• Klarna testing requires customer details

• terminals with type = virtual may require refundEmail for certain flows

• terminals with type = physical may have a different minimum request shape

If you are documenting a specific payment method or testing flow, use an example tailored to that terminal type and tender.

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 for OAuth APIs

  • Sandbox: /realms/nonprod/

  • Production: /realms/prod/

• Credentials match the environment

  • Sandbox API key, merchantId, and terminalId only work in Sandbox

  • Production API key, merchantId, and terminalId only work in Production

• Do not mix identifiers across environments A Production merchantId used with the Sandbox base URL, or a Sandbox merchantId used with the Production base URL, commonly results in 401 or 403.

Quick interpretation of common errors

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

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

• 403 Forbidden (Payments) The request is authenticated, but the API key is not permitted for the merchantId or terminalId you sent, or you are mixing environments.

• 403 Forbidden (Onboarding) The onboarding API key is valid, but it does not have permission for the requested action or environment. Confirm you are using the correct Production or Sandbox credential set.