Quick Start

Use this guide to get a Sandbox integration working end to end. Most partners begin with Payments. If you are focused on submitting merchant applications, follow the Onboarding path and then continue in the Onboarding section.

Pick a path

• Accept a payment (most partners start here)

• Submit a merchant application (onboarding integrators)

Before you begin

1) Get Sandbox credentials for your team

For the Payments path you will need:

• terminal API key (apiKey)

• merchantId

• terminalId

For the Onboarding path you will need:

• integrator username and password (OAuth)

• client_id for the integrator client

If you are missing any of the above, contact your Bead representative.

2) Confirm your environment base URLs and identity realm

Sandbox base URL for Payments:

• https://api.test.devs.beadpay.io

OAuth token URLs (used for Onboarding, Entity Management, and legacy Payments integrations):

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

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

3) Choose an HTTP client

Use curl, Postman, or your SDK. For most partners, curl is the fastest way to confirm connectivity and authentication.

Payments path

This path creates a hosted payment page, presents it to a customer, and confirms the result in Sandbox.

1) Authenticate (preferred)

Payments use header based authentication with a terminal API key.

Important notes:

• apiKey is the secret credential

• maskedApiKey is not usable

• send apiKey via the X-Api-Key header on every Payments request

Required headers:

• X-Api-Key: {apiKey}

• Content-Type: application/json

2) Create a hosted payment

Endpoint:

POST https://api.test.devs.beadpay.io/payments/crypto

Example curl:

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": {requestedAmount},
    "paymentUrlType": "web",
    "reference": "ORDER123"
  }'

Response fields to save:

• trackingId

• paymentPageId

• paymentUrls

3) Present the hosted page

Open the first URL in paymentUrls in a browser. The hosted page guides the customer through tender selection and payment completion.

Common patterns:

• Web checkout: open the URL in a new tab or embed it in an iframe

• Operations or in person demo: display the hosted page and have the customer scan the QR code with their wallet

4) Confirm payment status

You should confirm the final status before delivering goods or granting access.

Option A: Poll by trackingId

Endpoint:

GET https://api.test.devs.beadpay.io/payments/tracking/{trackingId}

Example curl:

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

Watch statusCode until it reaches a terminal state such as completed, expired, cancelled, underpaid, or overpaid.

Option B: Webhooks (recommended for production)

You can configure a terminal default webhook and optionally include additional webhookUrls per payment. Use webhooks to receive status changes automatically and reduce polling.

Troubleshooting (Payments)

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

• OAuth errors when calling Payments If you attempt OAuth client_credentials or other OAuth flows, you may see errors such as “Public client not allowed to retrieve service account”. Payments POST /payments/crypto uses X-Api-Key. Ignore the OAuth path for this endpoint.

• Hosted page does not load Confirm you are using a URL from the paymentUrls array returned by the API call.

Onboarding path

This path is for integrators that submit merchant applications through the API and track status through approval.

1) Authenticate (OAuth)

Onboarding and Entity Management use OAuth 2.0 (OpenID Connect token endpoint).

Token URLs:

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

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

Use the integrator client and your assigned username and password to request an access token. Then send that token as:

Authorization: Bearer {access_token}

Next steps:

• Continue in the Onboarding section to submit an application and generate a hosted signer link

• Use Entity Management after approval to create and maintain merchants, locations, and terminals

Legacy Payments authentication (supported for existing integrators)

Some existing Payments integrations authenticate using OAuth password grant with a terminal username and password, then send:

Authorization: Bearer {access_token}

New Payments integrations should use the terminal API key method described in the Payments path above.