Changelog

For the complete documentation index, see llms.txt. Append .md to any page URL for its markdown version.

• iOS and Android SDKs now available — The Banxa iOS SDK and Banxa Android SDK (both BanxaPaymentSDK) now wrap Banxa Hosted Checkout for native mobile apps. iOS is distributed through Swift Package Manager and Android as an AAR. Both are headless: startPayment(request:controller:) on iOS and the StartPayment composable on Android create the order and present checkout in one call, then report the outcome on a delegate or callback lambdas. Both use x-api-key authentication and require no backend for core flows. Note: they cover buy orders only, and do not expose order lookup or KYC sharing. Use the API or webhooks for those. → iOS SDK Guide · Android SDK Guide

• Nonce should now be generated in microseconds (16 digits) — All HMAC documentation and code examples now generate the nonce as a Unix timestamp in microseconds. Seconds (10 digits) and milliseconds (13 digits) remain accepted, so this is non-breaking and requires no change to a working integration. Millisecond nonces collide under concurrent load and are rejected as reused (40003); microsecond precision reduces that materially. Note that padding a millisecond timestamp with three zeros does not help — the nonce must come from a clock with genuine sub-millisecond resolution. → Authentication & Environments
• Webhook nonce format documented — Banxa signs outbound webhooks with a 16-digit microsecond nonce. Webhook pages now state this explicitly, show a worked Authorization header, and instruct partners to treat the nonce as an opaque string rather than parsing or length-validating it. → Webhooks

• Sandbox card name requirement corrected — The name on the test card was documented as "any name". It must match the name entered at the billing details step, or the payment fails. → Sandbox Test Data
• Referral parameter reference corrected — The email parameter was documented but is not supported, and has been removed. Three descriptions were also wrong: fiatAmount and coinAmount can both be passed (fiatAmount takes precedence) rather than being mutually exclusive, blockchain is optional and falls back to the default configured for the selected coinType rather than being required with walletAddress, and encoding guidance no longer references email addresses. The parameter list now matches the supported set exactly. Docs only, non-breaking. → Supported Referral Parameters

• Sandbox test data corrected — Verification in sandbox is by email OTP, not mobile number: enter any email address, then code 7203. The list of Australian test mobile numbers has been removed. Document upload in sandbox accepts any legible image — no test document assets from Banxa are required. → Sandbox Test Data

• Third-Party Disclaimer requirement — Documents the go-live requirement to disclose Banxa as the third-party payment provider before checkout, with acceptable patterns and sample wording. → Third-Party Disclaimer
• Geographic & Asset Restrictions — The list of unsupported countries, jurisdiction-specific asset restrictions, and how restriction errors map to causes. → Geographic & Asset Restrictions
• Refunds & Chargebacks — How refunds are triggered, flow of funds, chargeback liability and the 120-day window, and common failure reasons. → Refunds & Chargebacks
• Outbound IP Addresses — Banxa's outbound IPs per environment for partners that allowlist webhook traffic. → Outbound IPs

• FAQ page — Answers to the most common integration questions raised by partners: credential types, sandbox behaviour, order finality, fee model, externalCustomerId semantics, and webhook handling. → FAQ
• Error code reference — Documents 4002, 4005, 5034, 422 code 81, common 401 causes, and checkout errors, none of which were previously documented. → Error Codes
• Sandbox limitations — The Testing Overview now lists what sandbox does not do: no on-chain transactions, no Sumsub connection, manual order fulfilment, no failure simulation, stale pricing, no emails, no Apple Pay or Google Pay. → Testing Overview
• Order identifiers section — Order Statuses now defines the customer-facing numeric order ID vs the API order key, and which to reconcile on. → Order Statuses
• JS Native Payments SDK now available (web): The Banxa JS Native Payments SDK (@banxa-official/javascript-native-payments-sdk, v1.0.0) is now available for web apps. A Node-safe BanxaApiClient handles order creation and quotes server-side, and the <banxa-hosted-checkout> web component embeds the checkout in an iframe. A web integration guide and full SDK reference are now published. → JS Native Payments SDK (Web) Guide

• Webhook signing secret clarified — The Securing Webhooks section now states explicitly that webhook signatures are verified with the HMAC key pair, not the v2 x-api-key. Previous wording implied a v2 secret that does not exist. Non-breaking, docs only. → Webhooks
• Order finality warning — Order Statuses now warns that paymentReceived is not a settlement guarantee and that partners must settle on complete. → Order Statuses
• Quote usage notes expanded — Get a Quote now states there is no quote ID or validity window, explains the spread-in-rate fee model and why processingFee can be 0, and notes sandbox pricing staleness. → Get a Quote

• React Native SDK now available — The Banxa React Native SDK (@banxa-official/react-native-sdk) is now available. Install a single package to get typed methods for quotes, order creation, and in-app checkout presentation — no backend required for core flows. → SDK Integration
• Sumsub Copy Applicant support — A second Sumsub integration approach is now available alongside Reusable KYC. Copy Applicant retrieves name, DOB, selfie, document, address, and TIN directly from your Sumsub account, reducing the amount of data that needs to be collected separately. Copy Applicant is a separate Sumsub product and must be configured by Banxa — contact Banxa to have it enabled on your account. → Sumsub Integration

• KYC status webhooks — Banxa now sends a webhook when a customer's identity verification status changes. The payload includes kyc.status with values PENDING, UNDER_REVIEW, ACTION_REQUIRED, VERIFIED, and REJECTED. Use this to track verification progress without polling for order status. → Webhooks

• mobileNumber now optional on KYC token share — Previously required on POST /v2/identities/token/share. Note: Interac (Canada) requires a mobile number — if not provided, Banxa collects it from the customer during checkout.

• partnerFee now included in Quote and Order responses — Quote and order responses now include partnerFee, providing direct visibility of partner fees during pricing and reconciliation.
• KYC token sharing via Sumsub added — POST /v2/identities/token/share is now supported. Share a verified customer's Sumsub token with Banxa to pre-populate KYC and reduce friction at checkout. → KYC Sharing

• Webhook payloads now include full order context — Webhooks now include full order context for all status transitions, removing the need for a follow-up Get Order call for reporting and reconciliation.

• Base64-encoded images now accepted for identity documents — Identity document images can now be submitted as Base64-encoded strings in addition to secure HTTPS URLs.

• Automated webhook retries — If Banxa does not receive a 200 OK response, the webhook is automatically retried. The payload remains unchanged across retry attempts.

• contract_id added to Get Coins and Get Order(s) responses — Enables additional reporting on cryptocurrency/blockchain smart contract values.

• Webhooks Version 2 — Webhooks are now sent for all order status transitions. Payloads include full order context — no follow-up Get Order call required.

• Discount code support — Available via Get Prices and Create Order endpoints. Commission rate can now be adjusted on a per-quote or per-order basis.
• X-Request-Id response header — Included in all Banxa API responses. Use this value when troubleshooting with Banxa support.

• Referral URL theme parameters added — New URL parameters for visual customisation: theme, primaryColor, secondaryColor, backgroundColor, textColor.