Withdraw from Card

Withdraw funds from a virtual card back to your wallet

Endpoint: POST https://api.uncash.io/api/v1/cards/{id}/withdraw

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The card ID (UUID) to withdraw from

Body Parameters

Parameter	Type	Required	Description
amount	number	Yes	Amount to withdraw from the card (minimum: 1.00, maximum: 10,000.00)

Response

Success Response

Field	Type	Description
success	boolean	Indicates if the withdrawal was successful
message	string	Success message
timestamp	string	ISO 8601 timestamp

Data Object

Field	Type	Description
card_id	string	Card ID (UUID) that was withdrawn from
transaction_id	string	Transaction ID (UUID) for this withdrawal
invoice_id	number	Invoice ID for this transaction
wallet_balance	number	New wallet balance after withdrawal
new_card_balance	number	New card balance after withdrawal
amount_withdrawn	number	Amount withdrawn

Request Example

cURL

curl -X POST https://api.uncash.io/api/v1/cards/card-id/withdraw \
  -H "Authorization: Bearer uc_your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10
  }'

JavaScript

const response = await fetch('https://api.uncash.io/api/v1/cards/card-id/withdraw', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer uc_your_api_token_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 10
  })
});

const data = await response.json();

Python

import requests

url = "https://api.uncash.io/api/v1/cards/card-id/withdraw"
headers = {
    "Authorization": "Bearer uc_your_api_token_here",
    "Content-Type": "application/json"
}
data = {"amount": 10}

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

Response Example

{
  "success": true,
  "message": "Card withdrawal successful",
  "data": {
    "card_id": "card-id",
    "transaction_id": "7f3a2b1c-4d5e-6f7g-8h9i-0j1k2l3m4n5o",
    "invoice_id": 00001,
    "wallet_balance": 100.0,
    "new_card_balance": 5,
    "amount_withdrawn": 10
  },
  "timestamp": "2025-11-22T11:20:15.123Z"
}

Validation Rules

• Minimum amount: $1.00
• Maximum amount: $10,000.00
• Decimal precision: 2 decimal places maximum
• Card balance: Card must have sufficient balance
• Cooldown: 15-minute cooldown between withdrawal attempts

Notes

Provider Withdrawal: The withdrawal is first processed with the card provider, then funds are credited to your wallet. This ensures balance consistency.

Error Responses

Insufficient Card Balance

{
  "success": false,
  "message": "Insufficient card balance. Available: 5.00, Requested: 10.00",
  "timestamp": "2025-11-22T10:00:00.000Z"
}

Cooldown Period

{
  "success": false,
  "message": "Please wait 15 minutes between withdrawals",
  "timestamp": "2025-11-22T10:00:00.000Z"
}

Card Not Ready

{
  "success": false,
  "message": "Card is not ready for withdrawals",
  "timestamp": "2025-11-22T10:00:00.000Z"
}

Validation Error

{
  "success": false,
  "message": "Invalid input data",
  "error": [
    {
      "code": "too_small",
      "minimum": 1,
      "type": "number",
      "inclusive": true,
      "exact": false,
      "message": "Minimum withdrawal amount is 1.00",
      "path": ["amount"]
    }
  ],
  "timestamp": "2025-11-22T10:00:00.000Z"
}