Skip to main content

1. Create the invoice on your backend

Send the invoice currency, amount, your order reference, an idempotency key, and the callback URL.
Set 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_at is not null

2. Redirect to the hosted page

Use the invoice_url from the response:
Do not construct or modify this URL yourself.

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.
Status mapping is a business decision. Do not fulfill goods or services until your backend has retrieved a completed invoice from the API.

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 without expiresAt 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.