Create Payment

To initiate a payment, your backend generates a hosted-payment URL. Customers open this URL, enter any required details, pick a payment method, and complete the transaction on Bead’s secure page.

Overview

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

• Supports crypto and digital-wallet payments

• Redirects the shopper back to your redirectUrl when finished

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
username=[e-mail]
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": "[e-mail]",
    "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": "[e-mail]"
}

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

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 a required field returns HTTP 400 – ValidationError.

• If you omit the entire customer object, the hosted page first asks the shopper for name and address (two short screens) before showing the payment-method screen.

Redirect the shopper to paymentUrls.url.

Step 3: Handle customer redirection

After the shopper completes or cancels payment, Bead redirects the browser to your redirectUrl. Use one of the status-confirmation methods below to determine the outcome.

Step 4: Confirm payment status

Option A – Webhook notifications (recommended) Configure a webhook URL; 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

• Register your webhook URL or schedule polling.

• Test end-to-end in sandbox.

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

• Need help? Email [e-mail].