Create Card

Create a new virtual card with automatic wallet deduction

Endpoint: POST https://api.uncash.io/api/v1/cards

Body Parameters

Parameter	Type	Required	Description
bin_id	string	Yes	BIN identifier for the card (get from /api/v1/bins)
name	string	Yes	Card nickname (1-255 characters)
planId	integer	Yes	Card plan ID (get from /api/v1/card-plans)
coupon_id	string	No	Optional coupon ID for discounts

Response

Success Response

Field	Type	Description
success	boolean	Indicates if the card was created successfully
message	string	Success message
timestamp	string	ISO 8601 timestamp

Data Object

Field	Type	Description
id	string	Database card ID (UUID)
category	string	Card category ("Wallet" or "Online")
status	string	Card status ("active")
balance	number	Initial card balance
address	object	Billing address object

Address Object

Field	Type	Description
city	string	City name
line1	string	Address line 1
line2	string | null	Address line 2 (optional)
state	string	State/Province
country	string	Country code
postalCode	string	Postal/ZIP code

Request Example

cURL

curl -X POST https://api.uncash.io/api/v1/cards \
  -H "Authorization: Bearer uc_your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "bin_id": "bin-id",
    "name": "My Business Card",
    "planId": 1
  }'

JavaScript

const response = await fetch('https://api.uncash.io/api/v1/cards', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer uc_your_api_token_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    bin_id: "bin-id",
    name: "My Business Card",
    planId: 1
  })
});

const data = await response.json();

Python

import requests

url = "https://api.uncash.io/api/v1/cards"
headers = {
    "Authorization": "Bearer uc_your_api_token_here",
    "Content-Type": "application/json"
}
data = {
    "bin_id": "bin-id",
    "name": "My Business Card",
    "planId": 1
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

Response Example

{
  "success": true,
  "message": "Card created successfully",
  "data": {
    "id": "card-id",
    "category": "Wallet",
    "status": "active",
    "balance": 10000,
    "address": {
      "city": "xx",
      "line1": "xx",
      "line2": null,
      "state": "xx",
      "country": "xx",
      "postalCode": "xx"
    }
  },
  "timestamp": "2025-11-22T08:27:06.832Z"
}

Notes

Wallet Deduction: The card creation fee is automatically deducted from your wallet balance. Ensure you have sufficient funds before creating a card.

Error Responses

Insufficient Balance

{
  "success": false,
  "message": "Insufficient balance. Required: 100.00",
  "timestamp": "2025-11-22T10:00:00.000Z"
}

Invalid BIN ID

{
  "success": false,
  "message": "Invalid BIN ID or BIN is disabled",
  "timestamp": "2025-11-22T10:00:00.000Z"
}

Validation Error

{
  "success": false,
  "message": "Invalid input data",
  "error": [
    {
      "code": "too_small",
      "minimum": 1,
      "type": "string",
      "inclusive": true,
      "exact": false,
      "message": "Card name is required",
      "path": ["name"]
    }
  ],
  "timestamp": "2025-11-22T10:00:00.000Z"
}