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.

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.

fiatAmountstringrequired

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.

cryptoAmountstringrequired

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 user wallet address that Banxa will use to send the crypto.

walletAddressTagstring

Wallet tag or memo associated with the wallet address. This is required when the Customer's wallet address has 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

externalCustomerIdstringrequired

Unique customer reference provided by you. Used to check whether customer has completed KYC.

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.

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: string' \
  -d '{
    "paymentMethodId": "string",
    "crypto": "string",
    "blockchain": "string",
    "fiat": "string",
    "fiatAmount": "string",
    "cryptoAmount": "string",
    "walletAddress": "string",
    "walletAddressTag": "string",
    "redirectUrl": "string",
    "subPartnerId": "string",
    "metadata": "string",
    "externalCustomerId": "string",
    "externalOrderId": "string",
    "discountCode": "string",
    "email": "string"
  }'

Responses

201

Bodyapplication/json
checkoutUrlstring
Example:"https://partner.banxa.com/portal?expires=xxx&oid=xxx&signature=xxx"
idstring
Example:"191fa5b4b1f45e1cf784422e09317d56"
externalIdstring
Example:"a4b427ccb872a1744b317456bd0d165f"
externalCustomerIdstring
Example:"awasdf-fg34fg-34hhsdf"
fiatstring
Example:"CAD"
fiatAmountstring
Example:"1000.00"
cryptostring
Example:"USDC"
cryptoAmountstring
Example:"696.63"
blockchainstring
Example:"TRON"
discountCodestring
Example:"XMAS"
Response
"{\n    \"checkoutUrl\": \"https://partner.banxa.com/portal?expires=xxx&oid=xxx&signature=xxx\",\n    \"id\": \"191fa5b4b1f45e1cf784422e09317d56\", // This is the Banxa defined Order ID\n    \"externalOrderId\": \"a4b427ccb872a1744b317456bd0d165f\", // If not provided, then this value will be null\n    \"externalCustomerId\": \"awasdf-fg34fg-34hhsdf\",\n    \"fiat\": \"CAD\",\n    \"fiatAmount\": \"1000.00\",\n    \"crypto\": \"USDC\",\n    \"cryptoAmount\": null, // If not provided, then this value will be null.\n    \"blockchain\": \"TRON\"\n}"
© Banxa 2026