Payment Webhooks

Overview

Payment Webhooks enable real-time notifications about the status of payment transactions. Instead of periodically checking the status of a payment, you can configure your system to receive immediate updates directly from Bead via webhook callbacks. This ensures your applications can react instantly to payment-related events such as transaction completions, underpayments, or payment expirations.

---

Key Benefits

• Real-Time Notifications: Get instant updates on transaction statuses.

• Reduced Complexity: Eliminates the need for repeated API calls to check payment statuses.

• Automation-Friendly: Integrate seamlessly with your internal systems for automated order processing, accounting updates, or customer communications.

---

Setting Up Webhooks

Webhooks are configured at the terminal level. Each terminal can have a single webhook URL set up to receive notifications. Use the Terminal Management API to configure or update the webhook.

Endpoint for Webhook Configuration:

• PUT /Terminals/{terminalId}/set-webhook-url

Example Request to Configure Webhook:

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

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

Example Successful Response:

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

---

Receiving Webhook Notifications

Bead will send HTTP POST requests to your configured webhook URL whenever there is a relevant event regarding a transaction.

Webhook Payload Example:

{
  "trackingId": "4f181348293946cfa39b5846078c9bbc",
  "paymentCode": "bAKbqtcuP5",
  "statusCode": 2,
  "amounts": {
    "requested": {
      "inPaymentCurrency": {
        "amount": 1.02,
        "currency": {
          "code": "USDC",
          "name": "USDC Ethereum"
        }
      },
      "inRequestedCurrency": {
        "amount": 1,
        "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}"
}

---

Webhook Status Codes

Below are common status codes included in webhook payloads:

Status Code	Meaning	Recommended Action
2	Payment Completed	Mark order as paid, notify customer
3	Payment Underpaid	Cancel the order, notify customer
4	Payment Overpaid	Mark order as paid, notify customer
7	Payment Expired	Cancel the order, notify customer
8	Payment Invalid	Cancel the order, notify customer
9	Payment Cancelled	Cancel the order, notify customer

For all cases except Payment Completed, the customer provides their email address via the Hosted Payment Page (if one was not provided in the payment request) and will receive instructions from Bead detailing how they can reclaim their funds. Note that while overpaid payments are considered paid, the overpaid amount must be reclaimed by the customer.

---

Handling Webhook Calls

To correctly process incoming webhook notifications:

1. Verify Webhook Origin: Ensure requests originate from Bead servers.

2. Validate Payloads: Check the payload structure and required fields.

3. Implement Business Logic: Use status codes to drive internal processes and customer notifications.

4. Acknowledge the Webhook: Always return an HTTP 200 OK response to confirm receipt and prevent retry attempts.

---

Testing Webhooks

Use the sandbox environment to test webhook integrations thoroughly:

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

• Sandbox Payment Notifications: Ensure test webhook URLs point to your test environment.

---

Next Steps

• Configure your webhook using the Terminal Management API.

• Test your webhook thoroughly using the sandbox environment.

• Ensure your system gracefully handles all webhook statuses and potential edge cases.