Create Payment

To initiate a payment, your backend (or client-side code) calls the Bead Payments API to generate a hosted-payment URL. Most integrators then embed this URL inside their application—commonly in an iframe, WebView, or browser control—so the shopper never leaves the merchant interface. You can also pop it into a new browser tab or window when your flow requires it. The customer sees Bead’s secure checkout, enters any required details, chooses a payment method, and completes the transaction.

Overview

• Endpoint: POST /payments/crypto (sandbox base https://api.test.devs.beadpay.io)

• Supports crypto and digital-wallet payments

• Redirects the shopper back to redirectUrl if provided

• Optional: webhookUrls – per-payment webhook array. Events go to the terminal’s default webhook plus every URL in the array.

Step 1 – 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,
  "token_type": "Bearer"
}

Use access_token as a Bearer token for the payment request.

Step 2 – Create a payment URL

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": [
    "https://yourwebsite.com/payments/webhook"               // OPTIONAL
  ]
}

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

Heads-up on webhooks If you include webhookUrls, Bead POSTs every payment-lifecycle event to:

1. The terminal’s default webhook, and

2. Each URL in the webhookUrls array.

Conditional customer-data rule

If any field inside customer is sent, all of these fields become required: firstName, lastName, email, address, address2, city, state, postalCode, countryCode. Omitting one returns HTTP 400 – ValidationError.

Step 3 – Handle completion (with or without redirect)

Scenario	Shopper experience
redirectUrl provided	After success or cancel, Bead redirects the browser to redirectUrl with query-string context.
No redirectUrl	Bead displays a branded “Payment complete” or “Payment cancelled” confirmation page.

Regardless of the redirect choice, confirm the final status via webhooks or polling.

Step 4 – Confirm payment status

Option A – Webhook notifications (recommended)

• Configure a terminal-level webhook and/or pass webhookUrls per payment.

• Your server receives real-time JSON payloads whenever statusCode changes.

Option B – Polling

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

Status codes: 2 Completed • 3 Underpaid • 4 Overpaid • 7 Expired • 8 Invalid • 9 Cancelled

Next steps

1. Register a default terminal webhook or supply webhookUrls in test calls.

2. Embed paymentUrls.url in your UI—or open it in a new window—to launch checkout.

3. Test end-to-end in sandbox.

4. When ready, request production credentials and switch to production endpoints.

Need help? Email [email protected].