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.

Hosted Checkout API (v2)