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

  • 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].

Last updated