Payment Webhooks

Payment webhooks let your application receive real-time callbacks whenever the status of a payment changes. Instead of polling the Payment Status endpoint, you can react immediately to events such as a transaction becoming completed, underpaid, or expired.

Key benefits

• Real-time notifications – instant status updates without polling

• Lower complexity – fewer API calls and simpler state management

• Automation-ready – drive order fulfilment, accounting, or customer comms as soon as events occur

Setting up webhooks

Webhooks are configured per terminal.

PUT /Terminals/{terminalId}/webhook

Example

PUT https://api.beadpay.io/Terminals/{terminalId}/webhook
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "webhookUrl": "https://yourserver.com/webhooks/payment-notifications"
}

Successful response:

{
  "terminalId": "{terminalId}",
  "webhookUrl": "https://yourserver.com/webhooks/payment-notifications",
  "updated": "2025-03-04T15:30:00Z"
}

---

Receiving webhook notifications

Bead sends an HTTP POST to your webhook URL whenever a payment’s status changes.

{
  "trackingId": "4f181348293946cfa39b5846078c9bbc",
  "paymentCode": "bAKbqtcuP5",
  "statusCode": "completed",
  "amounts": {
    "requested": {
      "inPaymentCurrency": { "amount": 1.02, "currency": { "code": "USDC", "name": "USDC Ethereum" } },
      "inRequestedCurrency": { "amount": 1.00, "currency": { "code": "USD",  "name": "USD" } }
    },
    "paid": {
      "inPaymentCurrency": { "amount": 1.02, "currency": { "code": "USDC", "name": "USDC Ethereum" } }
    }
  },
  "reference": "ORDER123",
  "description": "Transaction description",
  "receivedTime": "2025-03-04T15:30:45Z",
  "terminalId": "{terminalId}",
  "merchantId": "{merchantId}"
}

Note: statusCode now returns the enum word (e.g. "completed") rather than a numeric value.

---

Status values

Status Code	Meaning	Recommended action
created	Payment created; awaiting customer funds	No immediate action
processing	Funds detected; conversion in progress	Await final status
completed	Payment successful and converted	Mark order as paid, notify customer
underpaid	Customer sent less than requested	Cancel/hold order, notify customer
overpaid	Customer sent more than requested; requested amount converted	Mark order as paid, notify customer (customer must reclaim excess)
expired	Payment window elapsed with no funds	Cancel order, notify customer
invalid	Irregular event (multiple tx, unsupported asset, compliance block, extreme market)	Cancel order, notify customer
cancelled	Customer or merchant cancelled payment	Cancel order, notify customer
fullyRefunded (reserved)	Will indicate a full refund once refunds are supported	—
partiallyRefunded (reserved)	Will indicate a partial refund once refunds are supported	—

For underpaid, overpaid, expired, invalid, or cancelled outcomes, Bead prompts the customer for an email (if not already provided) and emails instructions to reclaim unconverted funds.

Handling webhook calls

1. Verify origin – confirm the request comes from Bead’s IP ranges or ensure the Authorization header matches a shared secret.

2. Validate payload – check required fields such as trackingId and statusCode.

3. Apply business logic – use the status to update orders, trigger refunds, etc.

4. Acknowledge – return HTTP 200 OK promptly; any non-2xx response triggers retries (exponential back-off).

Testing webhooks

Use the sandbox to exercise your integration:

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

• Point sandbox terminals at your test webhook URL.

Generate test payments and cycle through statuses to ensure your system handles each callback correctly.

Next steps

• Configure Webhooks alongside your Payment Status polling for full redundancy.

• Email [email protected] with integration questions.