Top Up Card

Add funds to a virtual card from your wallet balance

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

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The card ID (UUID) to top up

Body Parameters

Parameter	Type	Required	Description
amount	number	Yes	Amount to add to the card (minimum: 5.00, maximum: 10,000.00)

Response

Success Response

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

Data Object

Field	Type	Description
card_id	string	Card ID (UUID) that was topped up
transaction_id	string	Transaction ID (UUID) for this topup
invoice_id	number	Invoice ID for this transaction
wallet_balance	number	New wallet balance after topup
total_charged	number	Total amount charged from wallet (amount + platform fee)
platform_fee_amount	number	Platform fee charged for this topup
new_card_balance	number	New card balance after topup

Request Example

cURL

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

JavaScript

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

const data = await response.json();

Python

import requests

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

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

Response Example

{
  "success": true,
  "message": "Card topped up successfully",
  "data": {
    "card_id": "card-id",
    "transaction_id": "tx-id",
    "invoice_id": 00001,
    "wallet_balance": 1000.00,
    "total_charged": 1.0,
    "platform_fee_amount": 0.1,
    "new_card_balance": 10
  },
  "timestamp": "2025-11-22T11:14:39.907Z"
}

Validation Rules

• Minimum amount: $5.00
• Maximum amount: $10,000.00
• Decimal precision: 2 decimal places maximum
• Card limit: Topup amount + current deposit cannot exceed card limit
• Wallet balance: Must have sufficient balance (topup amount + platform fee)
• Cooldown: 2-minute cooldown between topup attempts on the same card

Notes

Platform Fee: A platform fee is charged based on the card type. The fee is automatically calculated and included in the total_charged amount deducted from your wallet.

Error Responses

Insufficient Balance

{
  "success": false,
  "message": "Insufficient wallet balance. Required: 105.40 (topup: 100.00 + platform fee: 5.40), Available: 50.00",
  "timestamp": "2025-11-22T10:00:00.000Z"
}

Card Limit Exceeded

{
  "success": false,
  "message": "Topup would exceed card limit. Current deposit: 500, Limit: 1000, Available: 500",
  "timestamp": "2025-11-22T10:00:00.000Z"
}

Cooldown Period

{
  "success": false,
  "message": "Please wait 87 seconds before topping up this card again",
  "timestamp": "2025-11-22T10:00:00.000Z"
}

Validation Error

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