Skip to main content
POST
/
cards
/
{id}
/
unload
Unload a card
curl --request POST \
  --url https://api.fyatu.com/api/v3.20/cards/{id}/unload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 25,
  "reference": "reclaim-op-002"
}
'
{
  "success": true,
  "status": 200,
  "message": "Card unloaded",
  "data": {
    "cardId": "crd_01HXYZ5555ABCDEF1111",
    "amount": 25,
    "currency": "USD",
    "reference": "reclaim-op-002",
    "transactionId": "ltx_01HXYZ9999ABCDEF3333"
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6a7b8c9d0e1f2",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-26T10:00:00Z"
  }
}

​
Overview

Transfers funds from a card back to your program ledger. Use this to reclaim unused balances, or to zero out a card before terminating it. The card must be ACTIVE — you cannot unload from a FROZEN card.

​
Path Parameters

ParameterTypeDescription
idstringThe card ID (prefix crd_)

​
Request Body

FieldTypeRequiredDescription
amountnumberYesAmount in full currency units (e.g. 25.00 = $25). Must not exceed the card’s current balance.
referencestringNoOptional caller-supplied reference echoed back in the response and webhook

​
Idempotency

Supply an Idempotency-Key header to safely retry without duplicating the transfer.

​
Example

curl -X POST https://api.fyatu.com/api/v3.20/cards/crd_01HXYZ5555ABCDEF1111/unload \
  -H "Authorization: Bearer $FYATU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unload-crd01HXYZ5555-op-002" \
  -d '{ "amount": 25.00, "reference": "reclaim-op-002" }'

​
Success Response (200)

{
  "success": true,
  "status": 200,
  "message": "Card unloaded",
  "data": {
    "cardId":        "crd_01HXYZ5555ABCDEF1111",
    "amount":        25.00,
    "currency":      "USD",
    "reference":     "reclaim-op-002",
    "transactionId": "ltx_01HXYZ9999ABCDEF3333"
  },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-26T10:00:00Z"
  }
}

​
Webhook

A CARD_UNLOADED event fires after a successful unload: 
{
  "event":      "CARD_UNLOADED",
  "eventId":    "evt_01HXY123456ABCDEF",
  "businessId": "BUS1A2B3C4D5E6F",
  "environment": "LIVE",
  "timestamp":  "2026-05-26T10:00:00Z",
  "data": {
    "cardId":        "crd_01HXYZ5555ABCDEF1111",
    "amount":        25.00,
    "currency":      "USD",
    "reference":     "reclaim-op-002",
    "transactionId": "ltx_01HXYZ9999ABCDEF3333",
    "timestamp":     "2026-05-26T10:00:00Z"
  }
}

​
Error Codes

CodeHTTPCause
CARD_NOT_FOUND404Card does not exist or belongs to another business/environment
CARD_ALREADY_TERMINATED422Card is already terminated
INSUFFICIENT_CARD_BALANCE422Requested unload amount exceeds the card’s current balance
INVALID_AMOUNT400Amount is zero or negative
PROVIDER_UNLOAD_FAILED422Card provider rejected the unload
INSUFFICIENT_SCOPE403Key lacks cards:write scope

Authorizations

​
Authorization
string
header
required

API key from the FYATU CaaS portal. Pass as Authorization: Bearer <key>.

Path Parameters

​
id
string
required

Body

application/json
​
amount
number<double>
required
Example:

25

​
reference
string
Example:

"reclaim-op-002"

Response

Card unloaded

​
success
boolean
Example:

true

​
status
integer
Example:

200

​
message
string
Example:

"Card unloaded"

​
data
object
​
meta
object