> ## 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.

# Order a Card

> Order a new card for the authenticated user

## Overview

Orders a new card for the authenticated user. This endpoint initiates the card provisioning process and returns immediately upon successful acceptance of the order.

<Note>
  **Prerequisites:**

  * User must have **VERIFIED** status (completed KYC)
  * User must not have an existing card
</Note>

<Warning>
  Currently, only **VIRTUAL** cards are supported. Physical card ordering will be available in a future release.
</Warning>

## Authentication

This endpoint requires authentication via Bearer token:

```bash theme={null}
Authorization: Bearer YOUR_ACCESS_TOKEN
```

## Request

### Headers

<ParamField header="x-client-key" type="string" required>
  Your public API client key
</ParamField>

<ParamField header="x-us-env" type="boolean" default={false}>
  Set to `true` to route requests to the US backend environment
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

### Body

<ParamField body="type" type="string" required>
  The type of card to order. Currently only supports `VIRTUAL`

  **Accepted Values:**

  * `VIRTUAL` - Digital card for online and mobile payments
</ParamField>

### Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://dev.api.baanx.com/v1/card/order \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "VIRTUAL"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://dev.api.baanx.com/v1/card/order', {
    method: 'POST',
    headers: {
      'x-client-key': 'YOUR_CLIENT_KEY',
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      type: 'VIRTUAL'
    })
  });

  const data = await response.json();
  console.log(data);
  ```

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

  url = "https://dev.api.baanx.com/v1/card/order"
  headers = {
      "x-client-key": "YOUR_CLIENT_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json"
  }
  payload = {
      "type": "VIRTUAL"
  }

  response = requests.post(url, headers=headers, json=payload)
  print(response.json())
  ```

  ```typescript TypeScript theme={null}
  interface OrderCardRequest {
    type: 'VIRTUAL';
  }

  interface OrderCardResponse {
    success: boolean;
  }

  const orderCard = async (): Promise<OrderCardResponse> => {
    const response = await fetch('https://dev.api.baanx.com/v1/card/order', {
      method: 'POST',
      headers: {
        'x-client-key': 'YOUR_CLIENT_KEY',
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        type: 'VIRTUAL'
      })
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    return await response.json();
  };
  ```
</CodeGroup>

## Response

### Success Response

<ResponseField name="success" type="boolean">
  Indicates whether the card order was accepted successfully
</ResponseField>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "success": true
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 400 - Bad Request theme={null}
  {
    "message": "User already has a card"
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "message": "Not authenticated"
  }
  ```

  ```json 403 - Forbidden theme={null}
  {
    "message": "Not authorized"
  }
  ```

  ```json 422 - Validation Error theme={null}
  {
    "message": "type field is required"
  }
  ```

  ```json 498 - Invalid Client Key theme={null}
  {
    "message": "Invalid client key"
  }
  ```

  ```json 499 - Missing Client Key theme={null}
  {
    "message": "Missing client key"
  }
  ```

  ```json 500 - Internal Server Error theme={null}
  {
    "message": "Internal server error"
  }
  ```
</ResponseExample>

## Common Error Scenarios

<AccordionGroup>
  <Accordion title="User Not Verified">
    **Error:** `400 Bad Request`

    **Cause:** User has not completed KYC verification

    **Solution:** Complete user verification before ordering a card. Check user status with `GET /v1/user/profile`
  </Accordion>

  <Accordion title="User Already Has Card">
    **Error:** `400 Bad Request`

    **Message:** `"User already has a card"`

    **Cause:** User already has an existing card

    **Solution:** Use `GET /v1/card/status` to retrieve existing card details instead of ordering a new one
  </Accordion>

  <Accordion title="Invalid Card Type">
    **Error:** `422 Validation Error`

    **Cause:** Invalid value provided for `type` field

    **Solution:** Ensure the `type` field is set to `VIRTUAL`. Physical cards are not yet supported.
  </Accordion>

  <Accordion title="Missing Authentication">
    **Error:** `401 Unauthorized`

    **Cause:** Missing or invalid Bearer token

    **Solution:** Ensure you include a valid access token in the Authorization header
  </Accordion>
</AccordionGroup>

## Next Steps

After successfully ordering a card:

1. **Check Card Status:** Use `GET /v1/card/status` to monitor the card provisioning status
2. **View Card Details:** Once active, use `POST /v1/card/details/token` to generate a secure token for displaying sensitive card information
3. **Set PIN:** Use `POST /v1/card/set-pin/token` to allow the user to set their card PIN
4. **Fund Card:** In custodial environments, link a wallet to the card for funding transactions

<Info>
  Card provisioning typically completes within a few seconds. The card status will change from `PENDING` to `ACTIVE` once ready for use.
</Info>

## Implementation Notes

### Card Lifecycle

1. **Order Placed:** `POST /v1/card/order` returns `success: true`
2. **Card Provisioning:** Backend systems provision the virtual card
3. **Card Active:** Card status becomes `ACTIVE` and is ready for transactions
4. **Card Usage:** User can make purchases using the card

### Best Practices

* Always check user verification status before attempting to order a card
* Implement proper error handling for all possible error codes
* Poll `GET /v1/card/status` after ordering to confirm card activation
* Inform users that only virtual cards are currently available
* Consider adding rate limiting to prevent duplicate card order attempts

### Security Considerations

* Never log or store the complete card details in your application
* Use secure token-based endpoints for displaying sensitive card information
* Implement proper access controls to ensure users can only order cards for themselves
* Validate user authentication before allowing card operations

## Related Endpoints

* `GET /v1/card/status` - Check card status and details
* `POST /v1/card/details/token` - Generate token to view card details
* `POST /v1/card/set-pin/token` - Generate token to set card PIN
* `POST /v1/card/freeze` - Temporarily disable card
* `GET /v1/user/profile` - Check user verification status