1. Create the invoice on your backend
Send the invoice currency, amount, your order reference, an idempotency key, and the callback URL.BILLIONS_API_URL=https://api-sandbox.billions.works while testing and
switch it to https://api.billions.works only for production.
See Create an invoice API for every request field and
its current schema type. The TypeScript SDK defaults to production when
baseUrl is omitted; set the sandbox host explicitly in test code.
Persist at least:
- The invoice
id order_no- The idempotency key used for the attempt
- The current invoice
status - The invoice expiration time, when
expires_atis notnull
2. Redirect to the hosted page
Use theinvoice_url from the response:
3. Treat the callback as a notification
When the callback arrives, extract the invoice identifier and retrieve that invoice from the authenticated API. Callback delivery may be duplicated or delayed, so processing must be idempotent.4. Update your order from the API response
The invoice status can include:
See Statuses and lifecycle for full status
definitions, including the refund request states behind
refund_processing.
5. Make completion idempotent
Callbacks and status checks can run more than once. Use a transaction or conditional update so inventory, emails, and fulfillment happen only on the first transition to paid.Expiration and payment amount differences
The current backend defaults an invoice withoutexpiresAt to two hours after
creation. Always store and use the response’s expires_at instead of assuming
that every invoice has the default lifetime. An expired or failed invoice
requires a deliberate new payment attempt with a new idempotency key.
Do not infer the treatment of an underpayment or overpayment from callback
amount fields. No general automatic adjustment or refund policy is published
for those cases. Retrieve the authoritative invoice, keep the order unpaid
unless its status is completed, and reconcile any amount discrepancy with
Billions support before fulfillment.