Quick Start

Follow these steps to integrate Bead’s Hosted Payment Page in the sandbox:

1. Request credentials

2. Authenticate

3. Create a payment

4. Verify status (webhook or polling)

5. Test end-to-end

Step 1 – Request sandbox access

Email [email protected]. You’ll receive:

Item	Description
API Key / Secret	For future endpoints that use key-based auth
Terminal credentials	{terminalId}@beadpay.io & password
Sandbox base URL	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...",
  "refresh_token": "eyJhbGciOi...",
  "expires_in":    3600,
  "token_type":    "Bearer",
  "scope":         "openid profile email"
}

Use access_token as a Bearer token for all subsequent 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",   // OPTIONAL
  "emailReceipt": true,
  "smsReceipt":   false,
  "refundEmail":  "[email protected]",

  "webhookUrls": [                                            // OPTIONAL
    "https://yourwebsite.com/payments/webhook"
  ]
}

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

Key points

• webhookUrls (optional) — adds extra endpoints in addition to the terminal’s default webhook.

• redirectUrl (optional) — omit it if you prefer Bead’s built-in “Payment complete / cancelled” page.

• Customer-data rule

  • If you send any field in customer, all of these become required: firstName, lastName, email, address, address2, city, state, postalCode, countryCode.

  • If you omit customer entirely, the hosted page does not prompt for name or address—collect them yourself if needed.

• Present paymentUrls.url to the shopper by embedding it in an iframe/WebView or opening a new tab.

Step 4 – Verify payment status

Option A — Webhook notifications (recommended)

• Configure a terminal webhook (via API or support) and/or pass webhookUrls.

• Bead POSTs a payload whenever statusCode changes.

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

• Return HTTP 200 quickly; any non-2xx triggers retries (exponential back-off).

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 fund the sandbox payment.

2. Ensure your UI embeds or opens the hosted page correctly.

3. Confirm that webhooks (or polling) capture the final statusCode.

Next steps

• Validate in sandbox, then request production credentials from Bead.

• Switch your base URLs to the production endpoints.

Questions? Email [email protected].