Unload Card

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"
  }
}

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 be ACTIVE — 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 the reference field. 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.

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 unloaded",
  "data": {
    "cardId":        "crd_01HXYZ5555ABCDEF1111",
    "amount":        25.00,
    "currency":      "USD",
    "reference":     "reclaim-op-002",
    "transactionId": "txn_01HXYZ9999ABCDEF3333"
  },
  "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

A CARD_UNLOADED event fires once the provider confirms the withdrawal and your program balance has been credited. It echoes the same reference and transactionId 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",
    "transactionId":      "txn_01HXYZ9999ABCDEF3333",
    "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
`transactionId`	the API response `transactionId`	The unload transaction record
`ledgerTransactionId`	—	The program-ledger entry created when your balance was credited

If the provider ultimately rejects the withdrawal, a CARD_UNLOAD_FAILED event fires instead, carrying the same reference and transactionId 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
`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

Authorization

string

header

required

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

Path Parameters

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

Show child attributes

Account

Products

Cardholders

Cards

Webhooks

Overview

Path Parameters

Request Body

Idempotency

Example

Success Response (200)

Webhook

Error Codes

Authorizations

Path Parameters

Body

Response

​Overview

​Path Parameters

​Request Body

​Idempotency

​Example

​Success Response (200)

​Webhook

​Error Codes

Authorizations

Path Parameters

Body

Response

Overview

Path Parameters

Request Body

Idempotency

Example

Success Response (200)

Webhook

Error Codes