Integration Best Practices

The externalCustomerId field is required in POST /v2/buy and POST /v2/sell requests. Banxa uses it to identify returning customers on your platform, avoiding repeated KYC collection and improving conversion.

Rules:

• Must be unique per customer on your platform.
• Must be consistent — use the same value every time the same customer creates an order.
• Must not be tied to anything that could become non-unique over time, such as a wallet address (customers may change wallets).

A stable internal user ID is the best choice.

Pass as many order parameters as possible when constructing a referral URL or creating an order via the API. Pre-filling fiat amount, crypto, blockchain, wallet address, and payment method reduces the number of steps the customer has to complete in the checkout flow and improves conversion.

Always call GET /v2/quotes immediately before presenting a price to the customer. Do not cache quote responses — crypto prices and payment method fees change frequently, and a stale quote can result in the customer seeing a different price at checkout.

If you are rendering the Banxa checkout in a WebView (mobile iFrame integration), configure the following:

• Local storage access must be enabled.
• Camera initialisation must be permitted (required for KYC document capture).
• HTML5 video playback must be allowed — Banxa uses <video> tags for KYC instructions. If video does not play on Android, enable WebChromeClient.
• allowsInlineMediaPlayback must be set to true; autoplay in fullscreen should be disabled.

Verify that neither the Feature-Policy nor Permissions-Policy headers on your page restrict camera or microphone access.

iOS note: KYC liveness checks (Sumsub) can only be completed in Safari or a SFSafariViewController-based WebView. Standard WKWebView does not support liveness capture on iOS.

→ For platform-specific implementation details, see Mobile Implementation — Embedded Checkout.