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
- Read the raw body and the X-Bolt-Webhook-Timestamp and X-Bolt-Webhook-Signature headers.
- 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.
- Read eventId and externalOrderId, associate the business order, accept confirmed payment results, and handle duplicates idempotently.
- Durably store the event and processing result, or enqueue it in your own persistent queue. For reviewed payments, check paidAmount and settlementType.
- 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 BodyStable identifier of the logical payment event, retained across retries and manual replays for deduplication.
Accept confirmed payment results in either CONFIRMED or COMPLETED state. Reviewed orders may also enter these states; check settlement details.
Final payable amount as a string, potentially including rounding or a matching offset. This is not the original product price submitted at creation.
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.
Recorded shortfall; zero for exact payment. Accepted overpayments may also return zero. Calculate amount minus paidAmount if a signed difference is needed.
EXACT, MANUAL_UNDERPAID, MANUAL_OVERPAID or MANUAL_AMBIGUOUS, describing the settlement or merchant-reviewed association.
Actual payment route: DIRECT for direct transfer, SPLIT for split payment. Queries may return null before settlement; this field is not payment confirmation.
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.
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.
Currently true only for MANUAL_UNDERPAID. Use settlementType to identify other manual handling.
The settlement currency, e.g., USDT / USDC.
Payment network code, such as TRC20, ERC20, BEP20, POLYGON, SOLANA or BASE.
The original merchant-side order ID used to match your business records.
Merchant receiving wallet used by this order; multiple orders may share it.
The blockchain transaction hash for on-chain traceability.
Recorded blockchain confirmation count. Rules differ by network; use the payment state to determine confirmation.
Recorded payment time as a date-time string; may be empty if unknown.
Recorded confirmation time as a date-time string; may be empty if unknown.
Recorded time of entry into COMPLETED. It is usually empty on first delivery and does not prove fulfillment by your business.
Custom metadata object passed through during checkout.
02. Acknowledge receipt
Success responseReturn 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.