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:
The request uses the Content-Type: application/json header.
The callback payload is not proof of payment. An attacker can send a request directly to a public callback endpoint. Retrieve the invoice using id and trust only the authenticated API response.

​
Safe callback algorithm

1

Accept the request

Parse only enough data to identify the invoice. Reject malformed requests without exposing internal error details.
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.

​
Security checklist

  • Keep API keys in server-side secret storage.
  • Require HTTPS for the callback endpoint.
  • Retrieve invoice state from the API before fulfillment.
  • 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 TypeScript and PHP SDKs include verifyInvoicePaid(). It retrieves the invoice, requires completed status, and compares callback status and paid amount with the API result.

​
Response behavior

Your endpoint should acknowledge a callback only after the event is stored or processed durably.
TODO: Add the delivery timeout, retry schedule, expected HTTP success codes, signature mechanism if applicable, and source IP policy after the callback delivery implementation is finalized.