Receive payment callbacks

After blockchain confirmation or merchant acceptance through review, BoltUtil sends an asynchronous POST to the order’s notifyUrl. This page describes callbacks for orders created through /api/v1/order/create; not every order-state change produces a notification.

Verify callback signatures

Read X-Bolt-Webhook-Timestamp (milliseconds) and X-Bolt-Webhook-Signature. With the matching Webhook configuration secret, compute HMAC-SHA256 over timestamp + "." + the raw body, encode it as hexadecimal, and compare in constant time. Signature verification protects message integrity; replay protection also requires a timestamp window and event deduplication.

Recipient processing flow

  1. Read the raw body and the X-Bolt-Webhook-Timestamp and X-Bolt-Webhook-Signature headers.
  2. Check the timestamp window, keep your server clock synchronized, and verify HMAC-SHA256 with your Webhook secret. The example allows five minutes before or after the current time.
  3. Read eventId and externalOrderId, associate the business order, accept confirmed payment results, and handle duplicates idempotently.
  4. Durably store the event and processing result, or enqueue it in your own persistent queue. For reviewed payments, check paidAmount and settlementType.
  5. Return HTTP 2xx after reliable acceptance. Also acknowledge duplicates already handled successfully; do not fulfill twice.

Verify the exact raw request body. Parsing and reserializing JSON may change whitespace, field order or encoding and invalidate the signature.

01. Callback body

POST / Request Body
eventIdSTRING

Stable identifier of the logical payment event, retained across retries and manual replays for deduplication.

statusSTRING

Accept confirmed payment results in either CONFIRMED or COMPLETED state. Reviewed orders may also enter these states; check settlement details.

amountSTRING

Final payable amount as a string, potentially including rounding or a matching offset. This is not the original product price submitted at creation.

paidAmountSTRING

Recorded paid amount as a string. Accepted underpayments may be lower than amount. Older orders without a separate paid amount may fall back to the payable amount.

shortfallAmountSTRING

Recorded shortfall; zero for exact payment. Accepted overpayments may also return zero. Calculate amount minus paidAmount if a signed difference is needed.

settlementTypeSTRING

EXACT, MANUAL_UNDERPAID, MANUAL_OVERPAID or MANUAL_AMBIGUOUS, describing the settlement or merchant-reviewed association.

paymentRouteSTRING

Actual payment route: DIRECT for direct transfer, SPLIT for split payment. Queries may return null before settlement; this field is not payment confirmation.

platformFeeSTRING

Actual platform fee in currency, returned as a string; queries may return null before it is recorded. Direct or fee-exempt payments use 0. Network fees are excluded.

merchantNetAmountSTRING

Merchant net receipts in currency, as a string. For split payments, gross paid amount minus platform fee. Queries may return null before recording; historical callbacks may fall back to paid amount.

manuallyAcceptedBOOLEAN

Currently true only for MANUAL_UNDERPAID. Use settlementType to identify other manual handling.

currencySTRING

The settlement currency, e.g., USDT / USDC.

networkSTRING

Payment network code, such as TRC20, ERC20, BEP20, POLYGON, SOLANA or BASE.

externalOrderIdSTRING

The original merchant-side order ID used to match your business records.

destinationAddressSTRING

Merchant receiving wallet used by this order; multiple orders may share it.

txHashSTRING

The blockchain transaction hash for on-chain traceability.

confirmationsINTEGER

Recorded blockchain confirmation count. Rules differ by network; use the payment state to determine confirmation.

paidAtSTRING

Recorded payment time as a date-time string; may be empty if unknown.

confirmedAtSTRING

Recorded confirmation time as a date-time string; may be empty if unknown.

completedAtSTRING

Recorded time of entry into COMPLETED. It is usually empty on first delivery and does not prove fulfillment by your business.

metadataOBJECT

Custom metadata object passed through during checkout.

02. Acknowledge receipt

Success response
!

Return HTTP 2xx after reliable acceptance

After completing processing or durably storing the event in your own processing queue, return HTTP 2xx, such as 200, 202 or 204. The example below has no response body; no specific JSON acknowledgement is required.

HTTP/1.1 204 No Content

* Do not return success before verifying the signature and reliably accepting the event. BoltUtil treats HTTP 2xx as successful delivery.

Duplicates and delivery retries

Failed deliveries are retried according to the applicable policy. Different callback formats currently use different retry rules; delivery time is not guaranteed. Check dashboard delivery logs and manually resend CONFIRMED or COMPLETED orders after fixing the receiver. Retries and replays can duplicate notifications; deduplicate by eventId or merchant order ID.

For this callback format, paidAt, confirmedAt and completedAt are yyyy-MM-dd HH:mm:ss strings without a timezone offset; unknown times may be empty strings. completedAt is usually empty on first delivery. These fields differ from the millisecond timestamp in the request header.

Resend payment notifications

Review delivery logs before resending.

Testing guidance

Start with the Webhook tester to generate signed requests for your receiver. Use resend for a real confirmed order only when needed, and prevent duplicate fulfillment. The cURL example uses simulated data for a test environment. The Java example persists an event; your system must implement business processing.