Skip to content

Create a buy order

Request

Allows your customer to create a buy crypto order with Banxa. Upon success, the response will contain a checkout URL which will be unique for the order. The customer will be redirected to this URL to complete the checkout process, which will expire after 1 minute if a redirect does not occur.

Path
partnerstringrequired

This is the partner code provided to you during onboarding. e.g. metamask.

Headers
Acceptstring
Default:"application/json"
x-api-keystring

This is the API Key that has been provided to you during onboarding.

Example:YOUR_API_KEY
Bodyapplication/json
paymentMethodIdstring

The payment method chosen by the user.

cryptostringrequired

This is the crypto type the customer wants to buy.

blockchainstring

This is the blockchain that is associated with the crypto token. If none is provided, then a default will be used.

fiatstringrequired

This is the fiat type the customer wants to buy.

fiatAmountstring

The amount of fiat the user wants to buy. Either fiatAmount OR cryptoAmount must be provided. If both are provided, then cryptoAmount will be used.

cryptoAmountstring

The amount of crypto the user wants to buy. Either fiatAmount OR cryptoAmount must be provided. If both are provided, then cryptoAmount will be used.

walletAddressstringrequired

The customer’s receiving wallet: the address Banxa sends the purchased crypto to.

walletAddressTagstring

Memo or tag of the customer’s receiving wallet. Required when the wallet uses a memo or tag, such as BNB (memo) and XRP (tag).

redirectUrlstringrequired

The URL the user will be redirected to after the buy flow has been completed. If the case of an order failure or cancellation, then the returnUrl will be appended with the status e.g. /?status=failure, /?status=cancel

subPartnerIdstring

Your defined ID for associating an order with. e.g. you may use this to differentiate between channels such as Exchange, Wallet, Web, Mobile.

metadatastring

Free form string that you can use to send us any information that will be returned in the Get Orders endpoint

externalCustomerIdstring

Unique customer reference provided by you. Recommended on every order: used to check whether the customer has completed KYC and to recognise returning customers.

externalOrderIdstring

An order ID that you may define and will be returned to you in a Get Order call.

discountCodestring

Allows you to configure the discount to your commission rate per order. This can be a promotion code such as XMAS or a way to differentiate between your customers.

emailstring

The user's email address that can be used to pre-populate the Banxa form.

ipBindingArray of objects, [ 1 .. 2 ] items

IP binding. The customer's IP address, taken from the customer's own request that started the order. One or two items, at most one per IP family. Required when Banxa has turned on IP binding for your account, unless you send ipBindingOmitted.

ipBindingOmittedstring

Sent instead of ipBinding when the customer uses iCloud Private Relay. Never sent together with ipBinding.

Value:"private_relay"
originalUrlstring, (uri)

The http or https URL of the page the customer was on. Stored with the order. URLs longer than 2,048 characters are cut, not rejected.

Example:"https://yourapp.com/buy"
curl -i -X POST \
  'https://docs.banxa.com/_mock/products/hosted-checkout/openapi/{partner}/v2/buy' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -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]"
  }'

Responses

Order created.

Bodyapplication/json
checkoutUrlstring

Checkout URL to redirect the customer to. Expires after 1 minute if a redirect does not occur.

Example:"https://partner.banxa.com/portal?expires=xxx&oid=xxx&signature=xxx"
idstring

Banxa order ID.

Example:"191fa5b4b1f45e1cf784422e09317d56"
externalOrderIdstring or null

The externalOrderId from the request. null if not provided.

Example:"a4b427ccb872a1744b317456bd0d165f"
externalCustomerIdstring
Example:"awasdf-fg34fg-34hhsdf"
fiatstring
Example:"CAD"
fiatAmountstring
Example:"1000.00"
cryptostring
Example:"USDC"
cryptoAmountstring or null

null if not provided in the request.

Example:"696.63"
blockchainstring
Example:"TRON"
discountCodestring

Present when a discountCode was applied.

Example:"XMAS"
Response
{
  "checkoutUrl": "https://partner.banxa.com/portal?expires=xxx&oid=xxx&signature=xxx",
  "id": "191fa5b4b1f45e1cf784422e09317d56",
  "externalOrderId": "a4b427ccb872a1744b317456bd0d165f",
  "externalCustomerId": "awasdf-fg34fg-34hhsdf",
  "fiat": "CAD",
  "fiatAmount": "1000.00",
  "crypto": "USDC",
  "cryptoAmount": null,
  "blockchain": "TRON"
}
© Banxa 2026