Create Buy Order

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.
`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	Yes	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	Secondary wallet identifier required by some blockchains (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.

Payment method IDs

debit-credit-card · apple-pay · sepa-bank-transfer · gbp-bank-transfer · ach-bank-transfer · payid-bank-transfer · upi · pix · 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"
  }'

PIX (BRL)

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",
    "blockchain": "ETH",
    "fiat": "BRL",
    "cryptoAmount": "0.0015",
    "walletAddress": "0xcbf80ee37fbf03307962576f327fc50b942e0591",
    "redirectUrl": "https://yourapp.com/order-complete",
    "paymentMethodId": "pix"
  }'

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.

Next step

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

→ See Redirecting to Checkout