Skip to main content
Use callbacks to wake your integration, not as proof of payment.

Callback payload

Billions sends an HTTP POST request with a JSON body:
For new integrations, data is the canonical event payload. Its fields are temporarily duplicated at the top level for backward compatibility.

Envelope fields

Invoice event fields

The request uses the Content-Type: application/json header.
Even a correctly signed callback is a notification, not the recommended source of payment truth. Retrieve the invoice using data.invoice_id and trust the authenticated API response before fulfillment.

Events and intermediate statuses

Callbacks can therefore report intermediate statuses such as processing and aml_check. Update visible payment state if useful, but fulfill an order only after the authenticated API returns completed. The complete invoice status reference is in Statuses and lifecycle.

Safe callback algorithm

1

Accept the request

Parse the JSON and read data.invoice_id. You may verify the signature as defense in depth, but do not make fulfillment depend only on callback data.
2

Retrieve the invoice

Call the authenticated Billions API with the invoice ID.
3

Match your records

Confirm the retrieved invoice belongs to the expected order_no and payment attempt.
4

Apply the transition once

Update the order in a database transaction and make side effects idempotent.
5

Return promptly

Respond successfully after durable processing, or enqueue slow work for a background worker.

Webhook signature

Every delivery includes:
Billions signs the entire parsed webhook object, including the envelope, top-level compatibility fields, and data. Both sides canonicalize that JSON value with RFC 8785 JCS:
The API key secret is used as UTF-8 text, not as hex-decoded bytes. It is the original secretKey displayed once when the API key was created. Reissue older API keys that do not have a signing secret. The official TypeScript, Python, and PHP SDKs provide this JCS verification method. Use the examples below when handling signatures without an SDK.

Verify in TypeScript / Node.js

Install an RFC 8785 implementation with npm install canonicalize:

Verify in PHP

Decode JSON as objects and canonicalize the resulting value with an RFC 8785 implementation. Do not replace JCS with ordinary json_encode() or a custom key sort.
JCS keeps array order, sorts object keys recursively by UTF-16 code units, and uses ECMAScript-compatible JSON serialization. Do not mutate string values, turn objects into arrays, or parse money into imprecise numbers before verification. Compare digests in constant time.

Test vector

The signature changes on retries because attempt and previous_attempt_timestamp change. event_timestamp remains stable. Do not reject a valid retry only because its event timestamp is old; deduplicate using webhook_id. Signature verification proves that the payload came from a holder of the API key secret. It does not make the webhook a better source of current state than the API. The recommended integration remains:
Use the returned invoice status, amount, settlement currency, and order_no for business decisions. This also handles missing or invalid signatures, delayed deliveries, and webhooks missed during downtime. The API returns the current invoice state, which may be newer than the event that triggered the callback.

Match the invoice to your order

Match the authenticated API response to the payment attempt you stored when creating the invoice: For a request denominated in USDT, the invoice can return settlement_currency: "USDT" and currency: "USDT_TRON". The latter identifies a network-specific internal ticker; it is not a mismatch with an order denominated in USDT. Keep the expected order amount and currency in your own records and stop fulfillment if the authenticated response differs. Fulfill only after that response also reports completed.
No stable callback source-IP range is published for allowlisting. Do not use an IP allowlist as your only authentication control. Use HTTPS, optional HMAC signature verification, and the authenticated invoice lookup. Contact Billions support if your network requires a published egress range.

Security checklist

  • Keep API keys in server-side secret storage.
  • Require HTTPS for the callback endpoint.
  • Retrieve invoice state from the API before fulfillment.
  • If you verify signatures, use RFC 8785 JCS and a constant-time comparison.
  • Keep the API key secret server-side and reissue legacy keys when necessary.
  • Compare the invoice to the stored order and expected amount.
  • Treat all callback fields as untrusted input.
  • Avoid logging API keys or complete sensitive payloads.
  • Rate-limit the callback endpoint.
  • Make duplicate delivery harmless.
The Python SDK provides get_invoice_from_webhook() for every event status. Its verify_invoice_paid() helper additionally requires completed status and compares the webhook status and paid amount with the API result.

Delivery and response behavior

Your endpoint should acknowledge a callback only after the event is stored or processed durably. Billions considers delivery successful only when the endpoint returns HTTP 200; other responses and transport errors are retried. Current delivery defaults:
  • Request timeout: 10 seconds.
  • Maximum delivery attempts: 10.
  • Retry delay: no earlier than 10 seconds after the previous attempt.
  • event_timestamp stays unchanged across retries.
  • attempt and previous_attempt_timestamp identify retry deliveries.
Each request also includes:
The ID, event, and attempt headers identify a delivery but do not authenticate it. Only X-Billions-Signature authenticates the payload, and the invoice API remains the source of truth before changing order state.