Create Buy Order

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

Create an on-ramp order (fiat → crypto) for a customer. Returns a checkoutUrl to redirect or embed so the customer can complete their payment.

Endpoint

POST /{partnerRef}/v2/buy

Request body

Field	Type	Required	Description
`crypto`	string	Yes	Cryptocurrency code (e.g., `ETH`, `BTC`, `USDT`).
`fiat`	string	Yes	Fiat currency code (e.g., `AUD`, `USD`, `EUR`).
`walletAddress`	string	Yes	Customer's receiving wallet address: where Banxa sends the crypto.
`redirectUrl`	string	Yes	URL to redirect the customer to after checkout completes or is cancelled.
`paymentMethodId`	string	No	Pre-selects a payment method. If omitted, the customer chooses in checkout. See supported values below.
`fiatAmount`	string	Conditional	Fiat amount to spend. Either `fiatAmount` or `cryptoAmount` must be provided.
`cryptoAmount`	string	Conditional	Crypto amount to receive. Either `fiatAmount` or `cryptoAmount` must be provided.
`blockchain`	string	No	Blockchain network (e.g., `ETH`, `BNB`). Required for multi-chain assets.
`externalCustomerId`	string	Recommended	Your stable identifier for this customer. Enables returning customer recognition and reduces repeat KYC. See best practices.
`email`	string	No	Customer's email address. Pre-populates the email field in checkout.
`externalOrderId`	string	No	Your own order reference to attach to this transaction. Banxa stores it and returns it in order responses and webhooks for reconciliation.
`walletAddressTag`	string	No	Memo or tag of the customer's receiving wallet, on chains that use one (e.g., memo for XLM, destination tag for XRP). Required when the destination wallet requires a tag.
`discountCode`	string	No	Discount code to apply to the order.
`subPartnerId`	string	No	Identifier for a sub-partner or segment within your account (e.g., different sites or resellers).
`metadata`	string	No	Additional free-form data to attach to the order. Returned as-is in order responses and webhooks.
`ipBinding`	array	Conditional	The customer's IP address, so Banxa can check that checkout is opened from the same network. One item per IP version (`v4`, `v6`), at most two. Required once Banxa turns on IP binding for your account, unless you send `ipBindingOmitted`. See IP Binding.
`ipBinding[].method`	string	Yes	`hash` (the exact address, hashed) or `range` (the network the address is in).
`ipBinding[].family`	string	Yes	`v4` or `v6`.
`ipBinding[].value`	string	Yes	For `hash`: 64 hexadecimal characters. See Hashing the IP address. For `range`: an IPv4 `/24` or IPv6 `/64` network with the host part set to zero, such as `203.0.113.0/24` or `2001:db8:1234:5678::/64`.
`ipBindingOmitted`	string	Conditional	Send `private_relay` instead of `ipBinding` when the customer uses iCloud Private Relay. No other value is accepted. Never send both.
`originalUrl`	string	No	The `http` or `https` URL of the page the customer started the order on. Banxa stores it with the order. Longer than 2,048 characters is shortened, not rejected.

Payment method IDs

debit-credit-card · apple-pay · sepa-bank-transfer · gbp-bank-transfer · payid-bank-transfer · upi · paypal

Example requests

Debit/credit card

curl -X POST "https://api.banxa-sandbox.com/{partnerRef}/v2/buy" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "crypto": "ETH",
    "fiat": "AUD",
    "fiatAmount": "200",
    "walletAddress": "0xe3BDEFdAeFF070925eB7FfC49F9B30c647Cb751e",
    "redirectUrl": "https://yourapp.com/order-complete",
    "paymentMethodId": "debit-credit-card",
    "externalCustomerId": "user_12345",
    "email": "[email protected]"
  }'

Apple Pay

curl -X POST "https://api.banxa-sandbox.com/{partnerRef}/v2/buy" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "crypto": "ETH",
    "fiat": "AUD",
    "fiatAmount": "300",
    "walletAddress": "0xe3BDEFdAeFF070925eB7FfC49F9B30c647Cb751e",
    "redirectUrl": "https://yourapp.com/order-complete",
    "paymentMethodId": "apple-pay",
    "externalCustomerId": "user_12345"
  }'

With IP binding

curl -X POST "https://api.banxa-sandbox.com/{partnerRef}/v2/buy" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "crypto": "ETH",
    "fiat": "AUD",
    "fiatAmount": "200",
    "walletAddress": "0xe3BDEFdAeFF070925eB7FfC49F9B30c647Cb751e",
    "redirectUrl": "https://yourapp.com/order-complete",
    "externalCustomerId": "user_12345",
    "ipBinding": [
      { "method": "hash", "family": "v4", "value": "31e085138870946bf3e30b6e6709089d14909607b10f1b2138ddc7aaa0d36057" },
      { "method": "range", "family": "v6", "value": "2001:db8:1234:5678::/64" }
    ],
    "originalUrl": "https://yourapp.com/buy"
  }'

Response

201 Created

{
  "checkoutUrl": "https://partner.banxa.com/portal?expires=xxx&oid=xxx&signature=xxx",
  "id": "191fa5b4b1f45e1cf784422e09317d56",
  "externalOrderId": "a4b427ccb872a1744b317456bd0d165f",
  "externalCustomerId": "user_12345",
  "fiat": "AUD",
  "fiatAmount": "200.00",
  "crypto": "ETH",
  "cryptoAmount": "0.04812",
  "blockchain": "ETH"
}

Field	Description
`checkoutUrl`	URL to redirect or embed for the customer to complete their transaction.
`id`	Banxa order ID. Store this for order lookup and reconciliation.
`externalOrderId`	Your order reference (`externalOrderId` from the request). Null if not provided.
`externalCustomerId`	The customer identifier you provided.
`fiat`	Fiat currency code (string).
`fiatAmount`	Fiat amount as a string.
`crypto`	Cryptocurrency code (string).
`cryptoAmount`	Crypto amount as a string.
`blockchain`	Blockchain network.

IP binding

IP binding is on for all new partners: every buy order must include the customer's IP address in ipBinding, or ipBindingOmitted for iCloud Private Relay customers. See the example request above.

→ See IP Binding for how to get the address, choose hash or range, and build the values.

Next step

Redirect the customer to checkoutUrl or load it in an iFrame/WebView.

→ See Redirecting to Checkout