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 how much of the payment experience you want to own, not by who runs KYC - KYC is configurable on both. Use the Banxa Native API when payments must happen inside your product: bank transfers run completely headless through the API, and card, Apple Pay and Google Pay run on a native payment sheet through a Banxa SDK, with no redirects or webviews. Use Banxa Hosted Checkout when you would rather Banxa ran the payment flow, or you want the broadest payment method coverage. Alternative payment methods such as PayPal, iDEAL, Klarna, PIX and VietQR are not supported headless, so most Native integrations create those particular orders through Hosted Checkout and use both products together.

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.

Legacy API (1.3)