Documentation Index
Fetch the complete documentation index at: https://docs.fyatu.com/llms.txt
Use this file to discover all available pages before exploring further.
Card Operations
Creating a Card
Two prerequisites: your business must have completed KYB verification, and the target cardholder must have kycStatus: ACCEPTED before a card can be issued to them.
POST /cards
{
"cardholderId": "CH1a2b3c4d5e6f",
"amount": 100.00,
"name": "JOHN DOE", // optional, defaults to cardholder name
"productId": "MCUSD1" // optional, defaults to default product
}
Fund
Add money to a card from your business wallet:
POST /cards/{cardId}/fund
{ "amount": 50.00 }
- A funding fee (percentage-based) may apply — see Card Fees
- Full amount is added to the card balance; fee is debited from your wallet separately
- Can fund a frozen card
Unload
Withdraw balance from a card back to your wallet:
POST /cards/{cardId}/unload
{ "amount": 25.00 }
- Cannot unload more than the available card balance
- An unloading fee may apply based on your pricing
Freeze / Unfreeze
Temporarily disable a card without losing its balance:
POST /cards/{cardId}/freeze // disable transactions
POST /cards/{cardId}/unfreeze // re-enable transactions
- Frozen cards cannot make purchases but retain their balance
- You can still fund or unload a frozen card
Terminate
Permanently close a card:
DELETE /cards/{cardId}
{
"reason": "Customer requested closure", // optional
"reference": "REF123456" // optional
}
{
"status": true,
"message": "Card terminated successfully",
"data": {
"id": "CRD678E4F2A1B3C9",
"status": "TERMINATED",
"reason": "Customer requested closure",
"refundedBalance": 25.00,
"terminatedAt": "2026-01-15T10:30:00+00:00",
"reference": "REF123456"
}
}
- Card cannot be reactivated after termination
- Cardholder can still have other active cards
- Provide a
reason for record-keeping (visible in webhooks and logs)
Replace
Issue a replacement card for a terminated card. The balance is transferred automatically:
POST /cards/{cardId}/replace
canIssue: false, the default product is used as a fallback.
Transactions
Transaction Types
| Type | Description |
|---|
debit | Purchase or payment (money leaves card) |
credit | Refund or cashback (money added to card) |
funding | Card funding operation |
unload | Card unloading operation |
Transaction Statuses
| Status | Description |
|---|
PENDING | Authorization hold |
COMPLETED | Successfully settled |
DECLINED | Transaction rejected |
REVERSED | Refunded or reversed |
GET /cards/{cardId}/transactions?page=1
Webhook Events
Card Lifecycle
| Event | Trigger |
|---|
card.created | New card issued |
card.funded | Funds added |
card.unloaded | Funds withdrawn |
card.frozen | Card frozen |
card.unfrozen | Card unfrozen |
card.suspended | System suspension (fraud, compliance, or 15 declines) |
card.reactivated | Suspension resolved |
card.terminated | Card permanently closed |
Transaction Events
| Event | Trigger |
|---|
card.transaction.authorized | Transaction approved |
card.transaction.declined | Transaction declined |
card.transaction.settled | Transaction settled |
card.transaction.reversed | Transaction reversed |
Error Codes
| Code | Cause | Resolution |
|---|
INSUFFICIENT_BALANCE | Wallet balance too low | Top up business wallet |
INSUFFICIENT_CARD_BALANCE | Card balance too low | Fund the card |
CARD_NOT_ACTIVE | Card is frozen, suspended, or terminated | Check status; unfreeze if frozen |
CARD_INACTIVE | Physical card not yet activated | Activate with activation code |
CARD_SUSPENDED | System suspension | Fund the card (decline suspension) or contact support |
CARD_TERMINATED | Card permanently closed | Issue a new card |
CARDHOLDER_INACTIVE | Cardholder not active | Activate the cardholder first |
BUSINESS_KYB_REQUIRED | Business verification incomplete | Complete KYB verification |
ALREADY_FROZEN | Card already frozen | No action needed |
ALREADY_ACTIVE | Card already active | No action needed |
DECLINE_LIMIT_REACHED | 15 insufficient funds declines | Fund the card to reset and reactivate |
Endpoints
