Question 1

Which API key do I use for which Banxa endpoint?

Accepted Answer

Banxa has two credential types, and using the wrong one is the most common cause of 401 Unauthorized errors. The v2 API key, sent in the x-api-key header, is for all /v2 endpoints: quotes, orders, payment methods, fiats, crypto and countries. The HMAC key pair, an API key plus secret, is for POST /v2/identities/token/share (KYC sharing) and for verifying incoming webhook signatures. Both credential sets are visible in the merchant dashboard, per environment.

Question 2

Is a Banxa quote a guaranteed price?

Accepted Answer

No. Quotes are indicative and carry no quote ID, so there is nothing to pass into order creation. The final price is confirmed at checkout. Re-quote whenever the customer changes amount, currency, or payment method.

Question 3

How long is a Banxa checkout URL valid?

Accepted Answer

The checkoutUrl returned by POST /v2/buy is valid for 1 minute, starting from Banxa's response to the order creation request. Once the URL has been loaded there is no further expiry. Create the order at the moment the customer confirms, then open the URL immediately. Do not create orders in advance.

Question 4

When is a Banxa order final?

Accepted Answer

Only the terminal statuses are final: complete, cancelled, declined and refunded. In particular paymentReceived is not final, because an order can still be cancelled after payment if it is held for risk or compliance review. Do not credit your customer or trigger downstream fulfilment until you receive complete.

Question 5

Which Banxa product should I integrate?

Accepted Answer

The choice is decided by who runs KYC. Use the Banxa Native API when your platform already runs its own KYC and wants no Banxa screens at all: it is headless, HMAC-signed server-to-server, and requires a backend. Use Banxa Hosted Checkout when you do not want to run KYC: Banxa handles identity, payment and delivery in its own flow, by redirect, embedded iFrame, or React Native SDK, with no backend required for the referral path. The Legacy API is maintained for existing integrations only.

Question 6

Does Banxa support OAuth for API authentication?

Accepted Answer

No. Banxa runs no OAuth authorization server and publishes no OpenID Connect discovery document. The Native API authenticates with HMAC-SHA256 signatures and Hosted Checkout with an x-api-key header. Credentials are issued to onboarded partners through the Partner Dashboard and cannot be provisioned programmatically.

HTTP status	Meaning
`400`	Request failed validation or a required feature is not enabled. Check the error `code` in the body.
`401`	Authentication failed. Wrong key type, wrong environment, or missing HMAC signature.
`422`	The request was well-formed but cannot be processed. Check the error `code` in the body.
`429`	Rate limit exceeded. Sandbox: 120 requests per minute per merchant account. Production: 500 requests per minute per IP. Back off and retry; prefer webhooks over polling.
`5xx`	Banxa-side error. Retry with backoff; contact support if persistent.

Code	Message	Cause and resolution
`4002`	Validation error	A field in the payload failed backend validation. A common cause is `null` values in address or identity fields: optional fields must be a string or omitted entirely, never `null`.
`4005`	The feature is not enabled	The endpoint you are calling (most commonly KYC sharing) is not enabled on your account for this environment. Enablement requires a compliance review; contact your account manager.
`5034`	Coin restriction	The requested crypto asset is not available for the customer's region. For example, stablecoins are not available to customers in Canada.

Symptom	Cause
`401` on `/v2` endpoints	Using sandbox credentials against production (or vice versa), or a malformed `x-api-key` header. The correct base URL per environment is shown in the merchant dashboard.
`401` on `POST /v2/identities/token/share`	This endpoint uses HMAC authentication, not `x-api-key`. Sign the request with your HMAC key pair. See Authentication & Environments.
Webhook signature verification failing	Verify with your HMAC secret, not the v2 `x-api-key`. See Webhooks.

Symptom	Cause
`checkoutUrl` no longer loads	The checkout URL is valid for 1 minute from order creation and must be loaded within that window (once loaded, it does not expire). Create the order when the customer confirms and open the URL immediately.
CSRF token mismatch	Stale checkout session, usually from reusing an old URL or a cached page. Have the customer refresh the page or retry; if it persists, create a fresh order.

Error Codes

HTTP status codes

Application error codes

Authentication errors

Checkout errors

Was this helpful?