> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baanx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Order

> Initiate an order for a product such as a premium account upgrade or metal card. Returns a unique order reference to pass to your payment gateway.

## Overview

Use this endpoint to start a new order for a product — for example, a premium account upgrade or a metal card. The response includes an `orderId` and, where applicable, a `paymentConfig` object containing everything needed to route the user through an external crypto payment flow.

Once you have an `orderId`, pass it to your payment gateway. After payment is submitted, poll [`GET /v1/order/:orderId`](/api-reference/order/get-order) to confirm the final outcome.

<Tip>
  Not sure which `productId` to use? Call [`GET /v1/order/products/available`](/api-reference/order/get-products) first to retrieve the list of products available and eligible for the current user.
</Tip>

## Request

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for the authenticated user. Format: `Bearer <userAccessToken>`
</ParamField>

<ParamField header="X-Client-ID" type="string" required>
  Your application's client ID, issued during onboarding.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

### Body

<ParamField body="productId" type="string" required>
  The unique identifier of the product to order. Valid values are partner-specific and returned by `GET /v1/order/products/available`. Example: `"PRODUCT_ID_ABC"`
</ParamField>

<ParamField body="paymentMethod" type="string" required>
  The payment method to use for this order. Supported values:

  * `CRYPTO_EXTERNAL_DAIMO`
</ParamField>

### Example Request

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch('https://api.baanx.com/v1/order', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Client-ID': 'your_client_id',
      'Authorization': `Bearer ${userAccessToken}`
    },
    body: JSON.stringify({
      productId: 'PRODUCT_ID_ABC',
      paymentMethod: 'CRYPTO_EXTERNAL_DAIMO'
    })
  });

  const { orderId, requestId, paymentConfig } = await response.json();
  // Pass orderId and paymentConfig to your payment gateway
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.baanx.com/v1/order',
      headers={
          'Content-Type': 'application/json',
          'X-Client-ID': 'your_client_id',
          'Authorization': f'Bearer {user_access_token}'
      },
      json={
          'productId': 'PRODUCT_ID_ABC',
          'paymentMethod': 'CRYPTO_EXTERNAL_DAIMO'
      }
  )

  data = response.json()
  order_id = data['orderId']
  payment_config = data.get('paymentConfig')
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.baanx.com/v1/order \
    --header 'Authorization: Bearer <userAccessToken>' \
    --header 'Content-Type: application/json' \
    --header 'X-Client-ID: your_client_id' \
    --data '{
      "productId": "PRODUCT_ID_ABC",
      "paymentMethod": "CRYPTO_EXTERNAL_DAIMO"
    }'
  ```
</CodeGroup>

## Response

### 200 — Success

The order has been created. Store `orderId` to track the order status. Use `paymentConfig` to initiate payment via your gateway.

```json theme={null}
{
  "requestId": "payment_1234",
  "orderId": "abcd_1234",
  "paymentConfig": {
    "paymentAmount": 199,
    "paymentCurrency": "USD",
    "destinationAddress": "0x3a11a86cf218c448be519728cd3ac5c741fb3424",
    "destinationChainId": "59144",
    "destinationTokenSymbol": "USDC",
    "destinationTokenAddress": "0x176211869cA2b568f2A7D4EE941E073a821EE1ff"
  }
}
```

<ResponseField name="requestId" type="string">
  An identifier for the payment request, used to correlate payment gateway callbacks back to this order. Example: `"payment_1234"`
</ResponseField>

<ResponseField name="orderId" type="string" required>
  Unique identifier for this order. Store this — you'll need it to poll for the order outcome via `GET /v1/order/:orderId`.
</ResponseField>

<ResponseField name="paymentConfig" type="object">
  Payment routing details for the external crypto payment. Pass these values to your payment gateway to initiate the transaction.

  <Expandable title="paymentConfig fields">
    <ResponseField name="paymentConfig.paymentAmount" type="number">
      The amount to be paid, denominated in `paymentCurrency`. Example: `199`
    </ResponseField>

    <ResponseField name="paymentConfig.paymentCurrency" type="string">
      The fiat currency for the payment amount. Example: `"USD"`
    </ResponseField>

    <ResponseField name="paymentConfig.destinationAddress" type="string">
      The on-chain wallet address to send the payment to.
    </ResponseField>

    <ResponseField name="paymentConfig.destinationChainId" type="string">
      The EVM chain ID for the destination network. Example: `"59144"` (Linea mainnet)
    </ResponseField>

    <ResponseField name="paymentConfig.destinationTokenSymbol" type="string">
      The token symbol to pay with. Example: `"USDC"`
    </ResponseField>

    <ResponseField name="paymentConfig.destinationTokenAddress" type="string">
      The contract address of the destination token on the specified chain.
    </ResponseField>
  </Expandable>
</ResponseField>

### Error Responses

<AccordionGroup>
  <Accordion title="401 — Authentication Error">
    The bearer token is missing, expired, or invalid. Ensure a valid user access token is included in the `Authorization` header.
  </Accordion>

  <Accordion title="403 — Authorization Error">
    The authenticated user does not have permission to perform this action.
  </Accordion>

  <Accordion title="422 — Validation Error">
    One or more required fields failed validation. Check that `productId` and `paymentMethod` are both present and that `paymentMethod` is a supported enum value (`CRYPTO_EXTERNAL_DAIMO`).
  </Accordion>

  <Accordion title="498 — Invalid Client Key">
    The `X-Client-ID` header value is not recognised. Verify your client ID.
  </Accordion>

  <Accordion title="499 — Missing Client Key">
    The `X-Client-ID` header is absent from the request.
  </Accordion>

  <Accordion title="500 — Internal Server Error">
    An unexpected error occurred on the server. Retry with exponential backoff. If the issue persists, contact Baanx support.
  </Accordion>
</AccordionGroup>

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Get Available Products" icon="list" href="/api-reference/order/get-products">
    Retrieve the products available and eligible for the current user before placing an order.
  </Card>

  <Card title="Get Order Status" icon="arrow-right" href="/api-reference/order/get-order">
    Poll for the async completion of a payment and confirm the order outcome.
  </Card>
</CardGroup>