Skip to main content
POST
/
api
/
v1
/
cards
/
{id}
/
topup
curl -X POST https://api.uncash.io/api/v1/cards/abc123/topup \
  -H "Authorization: Bearer uc_your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00
  }'

{
  "success": true,
  "data": {
    "card_id": "abc123",
    "transaction_id": "txn_456789",
    "new_balance": 250.00,
    "platform_fee": 5.00,
    "total_charged": 105.00
  },
  "message": "Card topped up successfully",
  "timestamp": "2025-09-26T10:30:00.000Z"
}

​
Path Parameters

​
id
string
required
The card ID to top up

​
Body Parameters

​
amount
number
required
Amount to add to the card (minimum: 5.00, maximum: 10,000.00)

​
Response

​
success
boolean
Indicates if the top-up was successful
​
data
object
​
message
string
Success message
curl -X POST https://api.uncash.io/api/v1/cards/abc123/topup \
  -H "Authorization: Bearer uc_your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00
  }'

{
  "success": true,
  "data": {
    "card_id": "abc123",
    "transaction_id": "txn_456789",
    "new_balance": 250.00,
    "platform_fee": 5.00,
    "total_charged": 105.00
  },
  "message": "Card topped up successfully",
  "timestamp": "2025-09-26T10:30:00.000Z"
}

​
Validation Rules

  • Minimum amount: $5.00
  • Maximum amount: $10,000.00
  • Decimal places: Maximum 2 decimal places
  • Card limits: Top-up cannot exceed the card’s maximum deposit limit
  • Wallet balance: Must have sufficient funds in wallet
Atomic Operation: The top-up process is atomic - it either succeeds completely or fails completely. Your wallet is only charged if the card top-up succeeds.

​
Error Responses

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