Quick Start

This guide walks you through creating a crypto payment, launching the hosted payment page, and confirming the final outcome. It also includes the required behavior for underpayments and overpayments.

What you will build

• Create a hosted crypto payment session

• Present the hosted payment page to a customer

• Confirm payment completion using webhooks or status polling

• Handle underpaid and overpaid outcomes correctly

• Understand the reclaim flow for any unconverted crypto

Prerequisites

You will need:

• A sandbox terminal API key (the secret apiKey, not a masked value)

• A sandbox merchantId and terminalId

• A server or tool capable of making HTTPS requests (curl, Postman, your backend)

Optional but recommended:

• A webhook endpoint for payment status updates

Environment and base URLs

Common sandbox base URL:

• https://api.test.devs.beadpay.io

Payments endpoints used in this quick start:

• POST /payments/crypto

• GET /payments/tracking/{trackingId}

Authentication used in this quick start:

• X-Api-Key: {apiKey}

Step 1: Create a payment

Create a hosted payment session and receive a trackingId plus one or more hosted paymentUrls.

Request

POST https://api.test.devs.beadpay.io/payments/crypto

Headers:

• X-Api-Key: {apiKey}

• Content-Type: application/json

• Accept: application/json

Minimal body:

{
  "terminalId": "TERM-123",
  "merchantId": "MERCH-456",
  "requestedAmount": 100.00,
  "paymentUrlType": "web",
  "reference": "ORDER-0001"
}

Recommended additions:

• refundEmail: If you have an email address for the payer, include it. This is the email Bead uses to send reclaim instructions when reclaim is required.

• redirectUrl: If you want the hosted experience to return the shopper to your confirmation page.

• webhookUrls: If you want webhooks for this payment in addition to any terminal level webhook configuration.

Example expanded body:

{
  "terminalId": "TERM-123",
  "merchantId": "MERCH-456",
  "requestedAmount": 100.00,
  "paymentUrlType": "web",
  "reference": "ORDER-0001",
  "description": "Sample order",
  "refundEmail": "[email protected]",
  "redirectUrl": "https://merchant.example.com/payment-return",
  "webhookUrls": [
    "https://merchant.example.com/webhooks/payments"
  ]
}

Example curl

curl -s -X POST "https://api.test.devs.beadpay.io/payments/crypto" \
  -H "X-Api-Key: {apiKey}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "terminalId": "TERM-123",
    "merchantId": "MERCH-456",
    "requestedAmount": 100.00,
    "paymentUrlType": "web",
    "reference": "ORDER-0001",
    "refundEmail": "[email protected]"
  }'

Response

You will receive a response similar to:

{
  "trackingId": "c10b29e3c8104e0f8dc139c20d9eeb6c",
  "paymentPageId": "a12b34c56d789e01",
  "paymentUrls": [
    "https://pay.qa.beadpay.io/crypto?paymentPageId=a12b34c56d789e01"
  ]
}

Save:

• trackingId: your lookup key for status, webhooks, reporting, and support

• paymentUrls[0]: the hosted payment page URL to present to the customer

Step 2: Present the hosted payment page

Open the hosted page URL from paymentUrls.

Common options:

• Web: open in a new tab or window, or embed (if allowed in your flow)

• Mobile: open in an in app browser or webview

• POS or terminal assisted: display the hosted page on a customer facing device

What the customer will do (typical crypto wallet flow):

1. Select an asset (example: BTC, USDC)

2. View a QR code or payment details

3. Open their wallet app and scan the QR code

4. Manually enter the crypto amount in their wallet app

5. Submit the transfer

Important: because the wallet requires the payer to enter an amount manually, miskeyed amounts can result in underpaid or overpaid.

Step 3: Confirm the final result

You should always confirm the final status before fulfilling an order. Use either webhooks or status polling.

Option A: Webhooks (recommended)

If you configured webhooks (terminal level and or per payment webhookUrls), your server will receive events when the payment status changes.

Recommended handling:

• Verify the webhook signature if your configuration supports it

• Persist the event quickly

• Return 200 OK promptly

• Treat the webhook as the primary status signal

Option B: Polling

Use the tracking endpoint with the trackingId until the payment reaches a terminal status.

Request:

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

Example curl:

curl -s -X GET "https://api.test.devs.beadpay.io/payments/tracking/{trackingId}" \
  -H "X-Api-Key: {apiKey}" \
  -H "Accept: application/json"

Recommended polling behavior:

• Use a reasonable interval (example: 2 seconds) during an active checkout

• Stop polling once a terminal status is returned

• Prefer webhooks for production scale

Step 4: Handle status outcomes

The payment status is returned in statusCode.

Non terminal statuses

statusCode	Meaning
created	Payment created, waiting for customer action
processing	Funds detected and processing is in progress

Terminal statuses

statusCode	Meaning	What you should do
completed	Customer paid the requested amount	Fulfill and mark as paid
underpaid	Customer sent less than requested	Treat as not successful payment, do not fulfill
overpaid	Customer sent more than requested	Treat as successful payment for the requested amount
expired	Payment window ended without a valid completion	Treat as not successful payment, do not fulfill
invalid	Irregular condition, funds not eligible for conversion	Treat as not successful payment, do not fulfill
cancelled	Payment cancelled	Treat as not successful payment, do not fulfill

Underpayments and overpayments

Underpayments and overpayments occur because the payer manually enters the crypto amount in their wallet app.

Underpaid

Definition: the payer sent less than the requested amount.

Integrator behavior:

• Treat as not successful payment

• Do not fulfill the order

• If the customer still wants to pay, create a new payment and start a new hosted checkout session

What Bead does:

• The crypto received remains unconverted

• The full amount received is returned to the payer through the reclaim process

Overpaid

Definition: the payer sent more than the requested amount.

Integrator behavior:

• Treat as successful payment for the requested amount

• Fulfill once you confirm the terminal status

• Do not attempt to refund the overage yourself

What Bead does:

• The requested portion is processed and settled

• The overage remains unconverted and is returned to the payer through the reclaim process

Reclaiming unconverted crypto

Reclaim is how Bead returns any unconverted crypto to the payer.

Reclaim can occur when the payment is:

• underpaid

• overpaid (overage only)

• expired

• invalid

• cancelled

Email behavior for reclaim

• If you provided refundEmail in the Create Payment request, Bead emails reclaim instructions to that address when reclaim is required.

• If refundEmail was not provided, the hosted payment page prompts the payer to enter an email address in underpaid and overpaid outcomes so Bead can send reclaim instructions.

Recommended best practice:

• Provide refundEmail whenever you have it, especially for digital and virtual checkout flows.

Troubleshooting

401 Unauthorized

Common causes:

• Missing X-Api-Key header

• Using a masked value instead of the real apiKey

• Using a key from the wrong environment

Hosted payment page does not load

Common causes:

• Using an old or incorrect paymentUrls value

• Terminal is not configured for the tender types you are testing

• Environment mismatch between API base URL and hosted page environment

Status never reaches a terminal state

Common causes:

• Customer did not complete the wallet transfer

• Customer sent funds after the payment expired

• Webhook endpoint is failing and you are relying only on webhooks without polling

Next steps

After you complete this quick start in sandbox:

• Review Payment Statuses for full status definitions and guidance

• Review Under and Over Payment Handling for detailed integrator workflows

• Review Reclaiming Unconverted Crypto to understand reclaim timing and payer experience

• Implement production grade webhooks and internal state mapping before going live