For the complete documentation index, see llms.txt. Append
.mdto any page URL for its markdown version.
Every Banxa order moves through a sequence of statuses from creation to completion. The order response from POST /v2/buy, POST /v2/sell, and GET /v2/orders all include an order status field.
You may want to group or map these statuses into something more meaningful for the experience you present to your customers.
| Status | Applies to | Definition |
|---|---|---|
pendingPayment | Buy (mainly) | Order has been created and the customer has submitted KYC information. Waiting for customer payment. Can appear briefly on sell orders. |
waitingPayment | Buy, Sell | Buy: customer has submitted payment information; waiting for final confirmation from external payment systems. Sell: waiting for the customer to send crypto to the provided wallet address. This webhook signals that cryptocurrency is ready to be sent to Banxa. |
paymentReceived | Buy, Sell | Payment confirmed. Buy: fiat payment received. Sell: crypto deposit received; the fiat payout is in progress. |
inProgress | Buy, Sell | Payment information has been received by external payment systems. The order is in final verification and processing. Also shown while an order is on hold. |
cryptoTransferred | Buy | Cryptocurrency transaction has been submitted to the blockchain. |
fiatTransferred | Sell | Webhook only; not returned by order lookup. The fiat payout has been sent. Sent for some payout methods, such as card payouts and ACH, before complete. |
complete | Buy, Sell | Order completed. Buy: deemed complete after 2 blockchain confirmations. Sell: deemed complete when fiat has been successfully sent to the customer. |
cancelled | Buy, Sell | Order cancelled by Banxa due to internal risk and compliance alerts, or because the IP Binding check blocked checkout. |
declined | Buy, Sell | Order declined by external payment systems. |
expired | Buy, Sell | Order created but payment not received within the expiry window. Expiry times vary by payment method. Buy: expired orders can become active again — if payment is received after expiry, the order will automatically continue through the normal processing stages. Sell: see Expiry and incorrect deposits. |
refunded | Buy, Sell | Order refunded by Banxa customer support at the customer's request. |
extraVerification | Buy | Order held for additional verification (e.g., ID or address verification). Banxa customer support will contact the customer to resolve the order. |
For instant payment methods (card, Apple Pay), waitingPayment may be bypassed.
The typical sell path is waitingPayment → paymentReceived → complete, with a fiatTransferred webhook before complete for some payout methods. Sell orders don't use cryptoTransferred or extraVerification.
waitingPayment is the signal for custodial integrations to execute the crypto transfer. The order webhook doesn't include the deposit address; get it from GET /v2/orders/{orderId}. Once Banxa receives the crypto (paymentReceived), the fiat payout is processed.
The following statuses are final — the order will not progress further:
completecancelleddeclinedrefunded
Note: for buy orders,
expiredis not always terminal. A buy order can resume if payment is received after the expiry time. For sell orders, see Expiry and incorrect deposits.extraVerificationis a hold state — the order will resume once verification is resolved by Banxa support.
paymentReceived is not a settlement guarantee. An order can still be cancelled and refunded after payment if it is held for risk or compliance review, and reviews can take hours in some cases. If you credit customers or trigger downstream fulfilment from order status, wait for complete.
Every order has two identifiers:
| Identifier | Format | Where it appears |
|---|---|---|
| Order ID | Short numeric | Shown to the customer in checkout and order emails |
| Order key | Long hash | API responses, webhook payloads, order lookup |
Always reconcile using the long hash. The short numeric ID is customer-facing only and is what customers will quote in support requests.
You can retrieve the current status of any order via the order lookup endpoint, or receive status updates automatically via webhooks.
→ See Order Lookup and Webhooks.