Skip to main content
POST
/
v1
/
card
/
order
{
  "success": true
}

​
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.
Prerequisites:
  • User must have VERIFIED status (completed KYC)
  • User must not have an existing card
Currently, only VIRTUAL cards are supported. Physical card ordering will be available in a future release.

​
Authentication

This endpoint requires authentication via Bearer token: 
Authorization: Bearer YOUR_ACCESS_TOKEN

​
Request

​
Headers

​
x-client-key
string
required
Your public API client key
​
x-us-env
boolean
default:false
Set to true to route requests to the US backend environment
​
Authorization
string
required
Bearer token for authentication

​
Body

​
type
string
required
The type of card to order. Currently only supports VIRTUALAccepted Values:
  • VIRTUAL - Digital card for online and mobile payments

​
Request Example

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"
  }'

​
Response

​
Success Response

​
success
boolean
Indicates whether the card order was accepted successfully
{
  "success": true
}

​
Error Responses

{
  "message": "User already has a card"
}

​
Common Error Scenarios

Error: 400 Bad RequestCause: User has not completed KYC verificationSolution: Complete user verification before ordering a card. Check user status with GET /v1/user/profile
Error: 400 Bad RequestMessage: "User already has a card"Cause: User already has an existing cardSolution: Use GET /v1/card/status to retrieve existing card details instead of ordering a new one
Error: 422 Validation ErrorCause: Invalid value provided for type fieldSolution: Ensure the type field is set to VIRTUAL. Physical cards are not yet supported.
Error: 401 UnauthorizedCause: Missing or invalid Bearer tokenSolution: Ensure you include a valid access token in the Authorization header

​
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
Card provisioning typically completes within a few seconds. The card status will change from PENDING to ACTIVE once ready for use.

​
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
  • 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