Close Card

Permanently close a virtual card and withdraw remaining balance to wallet

Endpoint: PATCH https://api.uncash.io/api/v1/cards/{id}/close

Path Parameters

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

Response

Success Response

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

Data Object

Field	Type	Description
card_id	string	Card ID (UUID) that was closed
balance_withdrawn	number	Amount withdrawn from card to wallet
transaction_id	string	Transaction ID (UUID) for the balance withdrawal (null if no balance)
invoice_id	number	Invoice ID for the withdrawal transaction (null if no balance)
new_wallet_balance	number	New wallet balance after withdrawal

Request Example

cURL

curl -X PATCH https://api.uncash.io/api/v1/cards/card-id/close \
  -H "Authorization: Bearer uc_your_api_token_here"

JavaScript

const response = await fetch('https://api.uncash.io/api/v1/cards/card-id/close', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer uc_your_api_token_here'
  }
});

const data = await response.json();

Python

import requests

url = "https://api.uncash.io/api/v1/cards/card-id/close"
headers = {"Authorization": "Bearer uc_your_api_token_here"}

response = requests.patch(url, headers=headers)
data = response.json()

Response Example

{
  "success": true,
  "message": "Card closed successfully",
  "data": {
    "card_id": "card-id",
    "balance_withdrawn": 15.00,
    "transaction_id": "tx-id",
    "invoice_id": 24929,
    "new_wallet_balance": 1434.14
  },
  "timestamp": "2025-11-22T11:25:30.456Z"
}

Behavior

• Balance Withdrawal: Any remaining balance on the card is automatically withdrawn to your wallet
• Provider Closure: The card is terminated at the provider level (irreversible)
• Database Update: Card status is set to "closed" in the database
• No Balance: If card has zero balance, no withdrawal transaction is created

Warning

Irreversible Action: Closing a card is permanent. The card cannot be reactivated after closure.

Validation Rules

• Card must have a valid provider_id (not 'temp')
• Card must not already be closed
• 15-minute cooldown between withdrawal/closure operations

Error Responses

Card Already Closed

{
  "success": false,
  "message": "Card is already closed",
  "timestamp": "2025-11-22T10:00:00.000Z"
}

Card Not Ready

{
  "success": false,
  "message": "Card not ready for closure",
  "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"
}

Provider Error

{
  "success": false,
  "message": "Failed to close card: Provider error message",
  "timestamp": "2025-11-22T10:00:00.000Z"
}