{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/hosted-checkout/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Integration Best Practices","description":"Official Banxa API documentation – on-ramp and off-ramp transfers with identity verification and compliance.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"integration-best-practices","__idx":0},"children":["Integration Best Practices"]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"externalcustomerid","__idx":1},"children":["externalCustomerId"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCustomerId"]}," field is required in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v2/buy"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v2/sell"]}," requests. Banxa uses it to identify returning customers on your platform, avoiding repeated KYC collection and improving conversion."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rules:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Must be ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["unique per customer"]}," on your platform."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Must be ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["consistent"]}," — use the same value every time the same customer creates an order."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Must ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," be tied to anything that could become non-unique over time, such as a wallet address (customers may change wallets)."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A stable internal user ID is the best choice."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"pre-fill-order-parameters","__idx":2},"children":["Pre-fill order parameters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"quote-call-frequency","__idx":3},"children":["Quote call frequency"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"webview-requirements","__idx":4},"children":["WebView requirements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you are rendering the Banxa checkout in a WebView (mobile iFrame integration), configure the following:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"required-settings","__idx":5},"children":["Required settings"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Local storage access must be enabled."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Camera initialisation must be permitted (required for KYC document capture)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["HTML5 video playback must be allowed — Banxa uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<video>"]}," tags for KYC instructions. If video does not play on Android, enable ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WebChromeClient"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowsInlineMediaPlayback"]}," must be set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},"; autoplay in fullscreen should be disabled."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"camera-access","__idx":6},"children":["Camera access"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Verify that neither the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Feature-Policy"]}," nor ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Permissions-Policy"]}," headers on your page restrict camera or microphone access."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["iOS note:"]}," KYC liveness checks (Sumsub) can only be completed in Safari or a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SFSafariViewController"]},"-based WebView. Standard ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WKWebView"]}," does not support liveness capture on iOS."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["→ For platform-specific implementation details, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/checkout-experience/iframe/webview-mobile"},"children":["Mobile Implementation — Embedded Checkout"]},"."]}]},"headings":[{"value":"Integration Best Practices","id":"integration-best-practices","depth":1},{"value":"externalCustomerId","id":"externalcustomerid","depth":2},{"value":"Pre-fill order parameters","id":"pre-fill-order-parameters","depth":2},{"value":"Quote call frequency","id":"quote-call-frequency","depth":2},{"value":"WebView requirements","id":"webview-requirements","depth":2},{"value":"Required settings","id":"required-settings","depth":3},{"value":"Camera access","id":"camera-access","depth":3}],"frontmatter":{"title":"Integration Best Practices for Banxa | Banxa Docs","description":"Best practices for Banxa integration: stable externalCustomerId, real-time quote calls, pre-filling order parameters, and WebView camera configuration.","seo":{"title":"Integration Best Practices"}},"lastModified":"2026-05-19T23:30:38.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/hosted-checkout/docs/getting-started/integration-best-practices","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}