Quick Start

Follow these steps to integrate Bead’s Hosted Payment Page in the sandbox. You will: request credentials → authenticate → create a payment → verify status → test end-to-end.

Step 1: Request sandbox access

Email [email protected]. You will receive:

• API Key and API Secret

• Terminal credentials for sandbox testing

Sandbox API base:   https://api.test.devs.beadpay.io/
Auth endpoint:      https://identity.beadpay.io/realms/nonprod/protocol/openid-connect/token

Step 2: Authenticate

POST https://identity.beadpay.io/realms/nonprod/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=password
client_id=bead-terminal
[email protected]
password=YOUR_TERMINAL_PASSWORD
scope=openid profile email

{
  "access_token": "eyJhbGciOi...",
  "expires_in": 3600,
  "refresh_token": "eyJhbGciOiJ...",
  "token_type": "Bearer",
  "scope": "openid profile email"
}

Use the access_token as a Bearer token for all API calls.

Step 3: Create a payment

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

{
  "terminalId": "TERM-123",
  "merchantId": "MERCH-456",
  "requestedAmount": 100.00,
  "paymentUrlType": "web",
  "reference": "ORDER-0001",
  "description": "Sample order",
  "customer": {
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Doe",
    "address": "123 Main St",
    "address2": "Suite 4B",
    "city": "Boston",
    "state": "MA",
    "countryCode": "US",
    "postalCode": "02108"
  },
  "redirectUrl": "https://yourwebsite.com/payment-success",
  "emailReceipt": true,
  "smsReceipt": false,
  "refundEmail": "[email protected]"
}

{
  "trackingId": "c10b29e3c8104e0f8dc139c20d9eeb6c",
  "paymentUrls": [
    {
      "type": "web",
      "url": "https://pay.test.devs.beadpay.io/payment-page"
    }
  ]
}

Important • If you include any field inside customer, all of these fields become required: firstName, lastName, email, address, address2, city, state, postalCode, countryCode. • Omitting a required field returns HTTP 400 – ValidationError. • If you omit the entire customer object, the hosted page first collects the shopper’s name and address (two short screens) and then shows the payment-method selection screen.

Redirect the shopper to paymentUrls.url.

Step 4: Verify payment status

Bead provides two options:

Option A – Webhook notifications (recommended)

• Register a webhook URL (via Bead support or the Terminal Management API).

• Your server receives real-time status updates.

{
  "trackingId": "4f181348293946cfa39b5846078c9bbc",
  "paymentCode": "bAKbqtcuP5",
  "statusCode": "completed",
  ...
}

Return HTTP 200 to acknowledge each webhook.

Option B – Polling

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

Response structure matches webhook payloads.

Step 5: Test the flow

1. Use a crypto test-net wallet to complete a sandbox transaction.

2. Confirm that the shopper is redirected correctly.

3. Verify that your webhook (or polling logic) records the final status.

Next steps

• Request production credentials from Bead.

• Switch your base URLs to the production endpoints.

• Questions? Email [email protected].