{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/hosted-checkout/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Create Buy Order","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":"create-buy-order","__idx":0},"children":["Create Buy Order"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create an on-ramp order (fiat → crypto) for a customer. Returns a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutUrl"]}," to redirect or embed so the customer can complete their payment."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"endpoint","__idx":1},"children":["Endpoint"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"POST /{partnerRef}/v2/buy\n"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"request-body","__idx":2},"children":["Request body"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["crypto"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cryptocurrency code (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ETH"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BTC"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USDT"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiat"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fiat currency code (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUD"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USD"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EUR"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["walletAddress"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Customer's receiving wallet address."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirectUrl"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["URL to redirect the customer to after checkout completes or is cancelled."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethodId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Pre-selects a payment method. If omitted, the customer chooses in checkout. See supported values below."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiatAmount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fiat amount to spend. Either ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiatAmount"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cryptoAmount"]}," must be provided."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cryptoAmount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Crypto amount to receive. Either ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiatAmount"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cryptoAmount"]}," must be provided."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["blockchain"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Blockchain network (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ETH"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BNB"]},"). Required for multi-chain assets."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCustomerId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your stable identifier for this customer. Enables returning customer recognition and reduces repeat KYC. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/getting-started/integration-best-practices#externalcustomerid"},"children":["best practices"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Customer's email address. Pre-populates the email field in checkout."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalOrderId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your own order reference to attach to this transaction. Banxa stores it and returns it in order responses and webhooks for reconciliation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["walletAddressTag"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Secondary wallet identifier required by some blockchains (e.g., memo for XLM, destination tag for XRP). Required when the destination wallet requires a tag."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["discountCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Discount code to apply to the order."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subPartnerId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Identifier for a sub-partner or segment within your account (e.g., different sites or resellers)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metadata"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Additional free-form data to attach to the order. Returned as-is in order responses and webhooks."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"payment-method-ids","__idx":3},"children":["Payment method IDs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["debit-credit-card"]}," · ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apple-pay"]}," · ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sepa-bank-transfer"]}," · ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["gbp-bank-transfer"]}," · ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ach-bank-transfer"]}," · ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payid-bank-transfer"]}," · ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["upi"]}," · ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pix"]}," · ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paypal"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example-requests","__idx":4},"children":["Example requests"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"debitcredit-card","__idx":5},"children":["Debit/credit card"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://api.banxa-sandbox.com/{partnerRef}/v2/buy\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"crypto\": \"ETH\",\n    \"fiat\": \"AUD\",\n    \"fiatAmount\": \"200\",\n    \"walletAddress\": \"0xe3BDEFdAeFF070925eB7FfC49F9B30c647Cb751e\",\n    \"redirectUrl\": \"https://yourapp.com/order-complete\",\n    \"paymentMethodId\": \"debit-credit-card\",\n    \"externalCustomerId\": \"user_12345\",\n    \"email\": \"customer@example.com\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"apple-pay","__idx":6},"children":["Apple Pay"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://api.banxa-sandbox.com/{partnerRef}/v2/buy\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"crypto\": \"ETH\",\n    \"fiat\": \"AUD\",\n    \"fiatAmount\": \"300\",\n    \"walletAddress\": \"0xe3BDEFdAeFF070925eB7FfC49F9B30c647Cb751e\",\n    \"redirectUrl\": \"https://yourapp.com/order-complete\",\n    \"paymentMethodId\": \"apple-pay\",\n    \"externalCustomerId\": \"user_12345\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"pix-brl","__idx":7},"children":["PIX (BRL)"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://api.banxa-sandbox.com/{partnerRef}/v2/buy\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"crypto\": \"ETH\",\n    \"blockchain\": \"ETH\",\n    \"fiat\": \"BRL\",\n    \"cryptoAmount\": \"0.0015\",\n    \"walletAddress\": \"0xcbf80ee37fbf03307962576f327fc50b942e0591\",\n    \"redirectUrl\": \"https://yourapp.com/order-complete\",\n    \"paymentMethodId\": \"pix\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"response","__idx":8},"children":["Response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["201 Created"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"checkoutUrl\": \"https://partner.banxa.com/portal?expires=xxx&oid=xxx&signature=xxx\",\n  \"id\": \"191fa5b4b1f45e1cf784422e09317d56\",\n  \"externalOrderId\": \"a4b427ccb872a1744b317456bd0d165f\",\n  \"externalCustomerId\": \"user_12345\",\n  \"fiat\": \"AUD\",\n  \"fiatAmount\": \"200.00\",\n  \"crypto\": \"ETH\",\n  \"cryptoAmount\": \"0.04812\",\n  \"blockchain\": \"ETH\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutUrl"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["URL to redirect or embed for the customer to complete their transaction."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Banxa order ID. Store this for order lookup and reconciliation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalOrderId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your order reference (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalOrderId"]}," from the request). Null if not provided."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCustomerId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The customer identifier you provided."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiat"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fiat currency code (string)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fiatAmount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fiat amount as a string."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["crypto"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cryptocurrency code (string)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cryptoAmount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Crypto amount as a string."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["blockchain"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Blockchain network."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-step","__idx":9},"children":["Next step"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redirect the customer to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutUrl"]}," or load it in an iFrame/WebView."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["→ See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/api-integration/redirecting-to-checkout"},"children":["Redirecting to Checkout"]}]}]},"headings":[{"value":"Create Buy Order","id":"create-buy-order","depth":1},{"value":"Endpoint","id":"endpoint","depth":2},{"value":"Request body","id":"request-body","depth":2},{"value":"Payment method IDs","id":"payment-method-ids","depth":2},{"value":"Example requests","id":"example-requests","depth":2},{"value":"Debit/credit card","id":"debitcredit-card","depth":3},{"value":"Apple Pay","id":"apple-pay","depth":3},{"value":"PIX (BRL)","id":"pix-brl","depth":3},{"value":"Response","id":"response","depth":2},{"value":"Next step","id":"next-step","depth":2}],"frontmatter":{"title":"Create a Buy Order — POST /v2/buy | Banxa Docs","description":"Create a fiat-to-crypto on-ramp order with POST /v2/buy. Returns a checkoutUrl. Full request body, required fields, and payment method examples.","seo":{"title":"Create Buy Order"}},"lastModified":"2026-05-19T23:30:38.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/hosted-checkout/docs/api-integration/create-buy-order","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}