Payment Webhooks

Use Payment Webhooks to receive payment lifecycle events in real time instead of polling for status changes. Webhooks are the recommended production pattern for tracking payment progress, updating orders, and driving downstream fulfillment or support workflows.

A webhook can be configured at the terminal level, and you can also include additional per-payment webhook URLs when creating a payment.

Why use webhooks

Use Payment Webhooks when you want to:

• receive payment status changes automatically

• reduce or eliminate polling against the tracking endpoint

• update internal order, invoice, or fulfillment state as soon as payment status changes

• support operational visibility and faster troubleshooting

For production use, webhooks should be your primary payment event mechanism. Use the tracking endpoint mainly for ad hoc checks, support workflows, and reconciliation of individual payments.

How webhook delivery works

When a payment status changes, Bead sends an HTTP request to the configured webhook endpoint with a JSON payload describing the payment event.

Webhook delivery behavior:

• events are sent from Bead to your server

• your endpoint should accept POST requests with JSON bodies

• your system should persist or queue the event quickly and return 200 OK

• if delivery fails, retries may occur based on Bead’s retry behavior for webhook delivery

Design your webhook consumer to be idempotent so repeated delivery of the same event does not create duplicate business actions.

Configuring the webhook URL

Terminal-level webhook configuration is managed on the terminal.

Use:

• PUT /Terminals/{id}/webhook to create or update the terminal webhook configuration

• DELETE /Terminals/{id}/webhook to remove the terminal webhook configuration

Do not document or rely on GET /Terminals/{id}/webhook for this path.

Terminal-level webhook example

PUT /Terminals/{id}/webhook

Use the current Terminal Management and API specification as the source of truth for the request body and supported fields for this operation.

Per-payment webhook URLs

When creating a payment, you can also include webhookUrls in the request body.

If webhookUrls are supplied, Bead sends payment lifecycle events to:

1. the terminal’s default webhook

2. each URL in the webhookUrls array for that payment

This is useful when:

• a specific order needs events routed to a temporary or context-specific endpoint

• you want one standard terminal webhook plus an additional workflow-specific listener

• different integrations need to observe the same payment lifecycle

Typical webhook payload usage

Webhook payloads may include more fields than your application needs. In most cases, your integration should focus on:

• payment identifiers such as trackingId

• the current payment status

• timestamps relevant to the event

• merchant or terminal identifiers when used for routing or support

Use the webhook event reference and spec as the source of truth for the exact payload schema.

Recommended event handling pattern

A good webhook processing flow is:

1. Receive the webhook request.

2. Validate and parse the payload.

3. Persist or enqueue the event immediately.

4. Return 200 OK quickly.

5. Process downstream business logic asynchronously.

6. Update internal records based on the payment status.

7. Use the tracking endpoint only when you need to confirm or troubleshoot a specific payment.

This pattern helps prevent timeouts and makes retries safer to handle.

Confirming status with the Tracking endpoint

Webhooks are the preferred real-time mechanism, but you can still confirm status on demand using the tracking endpoint.

Tracking endpoint

GET /payments/tracking/{trackingId}

Headers

Payments use header-based authentication.

X-Api-Key: {apiKey}
Accept: application/json

Notes:

• the API key is the secret credential

• the masked API key is not usable

• send the full API key value in the X-Api-Key header on every Payments request

Example curl

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

Use this endpoint when:

• a webhook delivery is delayed or under investigation

• support needs to verify the status of a single payment

• you need to reconcile a single payment event with your internal records

Best practices

• Use webhooks as the primary production signal Prefer webhooks over polling for payment lifecycle changes.

• Make webhook processing idempotent The same event may be delivered more than once. Your system should safely handle retries and duplicate deliveries.

• Acknowledge quickly Return 200 OK as soon as the event is safely persisted or queued.

• Keep secrets server-side Configure terminal webhook URLs and payment creation requests from secure backend systems only.

• Retain identifiers Store trackingId, merchantId, terminalId, and relevant internal order references so webhook events can be correlated quickly.

• Use the tracking endpoint selectively Polling every payment continuously is less efficient than webhook-driven processing.

Troubleshooting

• No webhook received Confirm a terminal webhook is configured or webhookUrls were included when the payment was created. Confirm your endpoint is publicly reachable.

• Webhook endpoint returns errors Check your application logs and make sure your endpoint returns 200 OK quickly after persisting or queueing the event.

• Duplicate events Make sure your consumer is idempotent and can safely ignore already-processed events.

• Need to verify final payment state Query GET /payments/tracking/{trackingId} using X-Api-Key.

Related pages

• Create Payment

• Payment Statuses

• Webhook Event Reference

• Terminal Management

• Reporting

• Settlement