Quick Start
Follow these steps to integrate Bead’s Hosted Payment Page in the sandbox:
Request credentials
Authenticate
Create a payment
Verify status (webhook or polling)
Test end-to-end
Step 1 – Request sandbox access
Email [email protected]. You’ll receive:
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
Use a crypto test-net wallet to fund the sandbox payment.
Ensure your UI embeds or opens the hosted page correctly.
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