Callback payload
Billions sends an HTTPPOST request with a JSON body:
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.
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:data. Both sides canonicalize that JSON
value with RFC 8785 JCS:
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 withnpm install canonicalize:
Verify in PHP
Decode JSON as objects and canonicalize the resulting value with an RFC 8785 implementation. Do not replace JCS with ordinaryjson_encode() or a custom
key sort.
Test vector
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.
Recommended verification: retrieve the invoice
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: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.
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 HTTP200; 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_timestampstays unchanged across retries.attemptandprevious_attempt_timestampidentify retry deliveries.
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.