Skip to main content
The Public API returns a status for three kinds of records: invoices, withdrawal requests, and refund requests. These are different status vocabularies. Always read the status from the authenticated API response; a callback is a notification that the invoice may have changed, not the source of truth.

Invoice statuses

The status field appears in invoice creation and retrieval responses. These are the values in the production OpenAPI schema: An invoice can move from completed to refund_processing, then to refunded. If a refund fails or is declined, the invoice can return to completed; inspect the refund request for the refund outcome. Do not assume that completed is the last possible invoice status.
Only an authenticated invoice lookup returning completed can authorize fulfillment. processing, aml_check, a customer’s return from checkout, or an invoice.paid callback on its own is not sufficient.

Withdrawal request statuses

The status field tracks the Billions withdrawal request. Public API-created requests currently start in processing, but clients must handle every documented value. success and rejected are terminal request outcomes. Do not treat processing as proof that the recipient has been paid.

Refund request statuses

The status field on a refund request is separate from the original invoice status. Public API-created refund requests currently start in processing. refunded, failed, and declined are terminal request outcomes. After a failed or declined refund, the original invoice can again report completed; that means the payment still stands, not that the refund succeeded.

Callback events

Native invoice callbacks have an event (invoice.status_changed or invoice.paid) plus previous_status and status. These describe an invoice transition, not a separate webhook-delivery status. Callback delivery may be delayed or retried, so retrieve the current invoice before acting. See Callbacks and security. For the request and response fields of money operations, see Withdrawals and refunds.