# 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](/products/hosted-checkout/docs/getting-started/integration-best-practices#externalcustomerid). |
| `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


```bash
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": "customer@example.com"
  }'
```

### Apple Pay


```bash
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)


```bash
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**


```json
{
  "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](/products/hosted-checkout/docs/api-integration/redirecting-to-checkout)