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"
}
'import requests
url = "https://api.fyatu.com/api/v3.20/cards/{id}/unload"
payload = {
"amount": 25,
"reference": "reclaim-op-002"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({amount: 25, reference: 'reclaim-op-002'})
};
fetch('https://api.fyatu.com/api/v3.20/cards/{id}/unload', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.fyatu.com/api/v3.20/cards/{id}/unload",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount' => 25,
'reference' => 'reclaim-op-002'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.fyatu.com/api/v3.20/cards/{id}/unload"
payload := strings.NewReader("{\n \"amount\": 25,\n \"reference\": \"reclaim-op-002\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.fyatu.com/api/v3.20/cards/{id}/unload")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 25,\n \"reference\": \"reclaim-op-002\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.fyatu.com/api/v3.20/cards/{id}/unload")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": 25,\n \"reference\": \"reclaim-op-002\"\n}"
response = http.request(request)
puts response.read_body{
"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"
}
}Cards
Unload Card
Return funds from a card back to your program ledger. POST /cards//unload. Requires cards:write scope.
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"
}
'import requests
url = "https://api.fyatu.com/api/v3.20/cards/{id}/unload"
payload = {
"amount": 25,
"reference": "reclaim-op-002"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({amount: 25, reference: 'reclaim-op-002'})
};
fetch('https://api.fyatu.com/api/v3.20/cards/{id}/unload', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.fyatu.com/api/v3.20/cards/{id}/unload",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount' => 25,
'reference' => 'reclaim-op-002'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.fyatu.com/api/v3.20/cards/{id}/unload"
payload := strings.NewReader("{\n \"amount\": 25,\n \"reference\": \"reclaim-op-002\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.fyatu.com/api/v3.20/cards/{id}/unload")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 25,\n \"reference\": \"reclaim-op-002\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.fyatu.com/api/v3.20/cards/{id}/unload")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": 25,\n \"reference\": \"reclaim-op-002\"\n}"
response = http.request(request)
puts response.read_body{
"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 beACTIVE — you cannot unload from a FROZEN card.
Unloading is asynchronous. A successful (
2xx) response means the request was accepted and is pending confirmation from the card provider — funds are not returned to the program ledger until confirmed, and the provider may still reject the unload. The unload transaction stays PENDING until confirmed. Use the CARD_UNLOADED (confirmed — ledger credited) and CARD_UNLOAD_FAILED (rejected — no credit) webhooks as the source of truth. Both echo the caller reference for reconciliation.Path Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The card ID (prefix crd_) |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
amount | number | Yes | Amount in full currency units (e.g. 25.00 = $25). Must not exceed the card’s current balance. |
reference | string | No | Optional caller-supplied reference echoed back in the response and webhook |
Idempotency
Unloads are idempotent on thereference field, and a reference is single-use. If you
retry an unload with the same reference for the same card, the API returns the original result
and does not withdraw again — a client retry or accidental double-submit can never drain the card
twice or produce a spurious INSUFFICIENT_CARD_BALANCE failure on the second attempt.
A
reference is final once it resolves. Both SETTLED and FAILED are terminal states of a
reference. If an unload resolves to FAILED, retrying the same reference returns
409 REFERENCE_ALREADY_FAILED — send a new reference to genuinely retry.Always send a stable, unique
reference per logical unload. The same reference you send here
is echoed back on the CARD_UNLOADED webhook (see below), so you can correlate the async result
with this response.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" \
-d '{ "amount": 25.00, "reference": "reclaim-op-002" }'
const resp = await fetch(
'https://api.fyatu.com/api/v3.20/cards/crd_01HXYZ5555ABCDEF1111/unload',
{
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.FYATU_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ amount: 25.00, reference: 'reclaim-op-002' })
}
);
const body = await resp.json();
console.log('Unloaded:', body.data.amount); // 25
console.log('Transaction:', body.data.transactionId);
import os, requests
resp = requests.post(
'https://api.fyatu.com/api/v3.20/cards/crd_01HXYZ5555ABCDEF1111/unload',
headers={'Authorization': f'Bearer {os.environ["FYATU_API_KEY"]}'},
json={'amount': 25.00, 'reference': 'reclaim-op-002'}
)
data = resp.json()['data']
print('Unloaded:', data['amount'])
print('Transaction:', data['transactionId'])
Success Response (200)
{
"success": true,
"status": 200,
"message": "Card unload accepted — pending provider confirmation",
"data": {
"cardId": "crd_01HXYZ5555ABCDEF1111",
"amount": 25.00,
"currency": "USD",
"reference": "reclaim-op-002",
"transactionId": "txn_01HXYZ9999ABCDEF3333",
"status": "PENDING"
},
"meta": {
"requestId": "req_01HXY123456ABCDEF",
"platform": "Fyatu CaaS",
"timestamp": "2026-05-26T10:00:00Z"
}
}
This 200 response means the unload was accepted and the card debit was initiated at the
provider. Settlement is confirmed asynchronously by the
CARD_UNLOADED webhook.Webhook
ACARD_UNLOADED event fires once the provider confirms the withdrawal and your program
balance has been credited. It echoes the same reference as the API response above, so you
can join the two directly:
{
"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",
"ledgerTransactionId": "ltx_01HXYZ0000ABCDEF4444",
"timestamp": "2026-05-26T10:00:00Z"
}
}
| Field | Matches | Meaning |
|---|---|---|
reference | your request + the API response | Your caller-supplied reference — the idempotency & correlation key |
ledgerTransactionId | — | The program-ledger entry created when your balance was credited |
CARD_UNLOAD_FAILED event fires instead,
carrying the same reference so you can reconcile the failure to your request.
Error Codes
| Code | HTTP | Cause |
|---|---|---|
CARD_NOT_FOUND | 404 | Card does not exist or belongs to another business/environment |
CARD_ALREADY_TERMINATED | 422 | Card is already terminated |
INSUFFICIENT_CARD_BALANCE | 422 | Requested unload amount exceeds the card’s current balance |
INVALID_AMOUNT | 400 | Amount is zero or negative |
REFERENCE_ALREADY_FAILED | 409 | This reference already resolved to FAILED and is single-use — send a new reference to retry |
CARD_WITHDRAWAL_UNAVAILABLE | 503 | Card withdrawal is temporarily unavailable — either paused by Fyatu, or a transient processing issue on our side. Nothing was moved; retry later. |
INSUFFICIENT_SCOPE | 403 | Key lacks cards:write scope |
Authorizations
API key from the FYATU CaaS portal. Pass as Authorization: Bearer <key>.

