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

​
Overview

Transfers funds from your program ledger to a specific card. The program ledger balance decreases by the funded amount; the card becomes spendable immediately. The card must be ACTIVE — you cannot fund a FROZEN or TERMINATED card.

​
Path Parameters

ParameterTypeDescription
idstringThe card ID (prefix crd_)

​
Request Body

FieldTypeRequiredDescription
amountnumberYesAmount in full currency units (e.g. 50.00 = $50). Must be greater than 0.
referencestringNoOptional caller-supplied reference (order ID, batch ID, etc.) echoed back in the response and webhook

​
Idempotency

This is a write operation — 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/fund \
  -H "Authorization: Bearer $FYATU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fund-crd01HXYZ5555-order-001" \
  -d '{ "amount": 50.00, "reference": "order-001" }'

​
Success Response (200)

{
  "success": true,
  "status": 200,
  "message": "Card funded",
  "data": {
    "cardId":        "crd_01HXYZ5555ABCDEF1111",
    "amount":        50.00,
    "currency":      "USD",
    "reference":     "order-001",
    "transactionId": "ltx_01HXYZ9999ABCDEF2222"
  },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-26T10:00:00Z"
  }
}

​
Webhook

A CARD_FUNDED event fires after a successful funding: 
{
  "event":      "CARD_FUNDED",
  "eventId":    "evt_01HXY123456ABCDEF",
  "businessId": "BUS1A2B3C4D5E6F",
  "environment": "LIVE",
  "timestamp":  "2026-05-26T10:00:00Z",
  "data": {
    "cardId":        "crd_01HXYZ5555ABCDEF1111",
    "amount":        50.00,
    "currency":      "USD",
    "reference":     "order-001",
    "transactionId": "ltx_01HXYZ9999ABCDEF2222",
    "timestamp":     "2026-05-26T10:00:00Z"
  }
}

​
Error Codes

CodeHTTPCause
CARD_NOT_FOUND404Card does not exist or belongs to another business/environment
CARD_FROZEN_CANNOT_FUND422Card is frozen — unfreeze before funding
CARD_ALREADY_TERMINATED422Card is already terminated
INSUFFICIENT_PROGRAM_BALANCE422Program ledger balance is too low
INVALID_AMOUNT400Amount is zero, negative, or exceeds the program load cap
PROVIDER_FUND_FAILED422Card provider rejected the funding — ledger has been reverted
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:

50

​
reference
string
Example:

"order-001"

Response

Card funded

​
success
boolean
Example:

true

​
status
integer
Example:

200

​
message
string
Example:

"Card funded"

​
data
object
​
meta
object