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.
Single-Use Cards
A single-use card is a virtual card that automatically terminates the moment its first purchase settles. Once the card is used and the transaction clears, Fyatu marks it TERMINATED and fires a CARD_TERMINATED webhook — no manual action required.
Single-use cards are ideal for:
- Vendor payments — one card per invoice, card is dead after payment settles
- Employee expense reimbursements — pre-approved amount, automatic cleanup
- Guest checkout — issue a disposable card to a customer, expire it after purchase
Single-use cards must be backed by a product with isOneTimeUse: true. Contact your account manager to enable this flag on a product. Single-use products must also have JIT enabled (hasJIT: true) — the program ledger, not a pre-loaded balance, authorises each transaction.
How It Works
1. Issue card → Fyatu creates VIRTUAL card, isSingleUse = true
HostFi receives a TRANSAMOUNT spend limit (e.g. $100)
Card is ACTIVE and ready to use
2. Cardholder pays → JIT authorization flow (see JIT Cards)
Fyatu checks program balance
Fyatu forwards to your CARD_AUTHORIZATION_VERIFY webhook
You APPROVE
HostFi executes transaction
3. Transaction clears → TRANSACTION_CLEARED fires
Fyatu calls HostFi to terminate the card
Card status → TERMINATED
CARD_TERMINATED fires (reason: SINGLE_USE_EXHAUSTED)
ACTIVE so the cardholder can use it again. Termination only fires on a settled, non-reversed clearing.
Issuing a Single-Use Card
The request is identical to any other card — the productId determines the card type. You may optionally set spendingLimit to override the default $100.00 per-transaction cap:
curl -X POST https://api.fyatu.com/api/v3.20/cards \
-H "Authorization: Bearer $FYATU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"productId": "prd_01HXYZOU123",
"spendingLimit": 250.00
}'
isOneTimeUse: true confirms the card will self-terminate:
{
"success": true,
"status": 201,
"message": "Card issued",
"data": {
"id": "crd_01HXYZ9999ABCDEF0001",
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"productId": "prd_01HXYZOU123",
"status": "ACTIVE",
"cardType": "VIRTUAL",
"cardBrand": "VISA",
"maskedPan": "445123******7890",
"last4": "7890",
"createdAt": "2026-05-28T10:00:00Z",
"updatedAt": "2026-05-28T10:00:00Z",
"nameOnCard": "Jane Smith",
"expirationDate": "05/2029",
"balance": 0.00,
"currency": "USD",
"features": {
"hasJIT": true,
"has3DS": true,
"hasApplePay": false,
"hasGooglePay": false,
"hasSpendControl": false,
"hasMccControl": false,
"isReloadable": false,
"isOneTimeUse": true
}
}
}
Spending Limit
| Field | Default | Description |
|---|
spendingLimit | 100.00 | Per-transaction cap sent to the card network. The card will be declined if a merchant attempts to charge more than this amount. |
spendingLimit maps to a TRANSAMOUNT limit type at HostFi — a single-transaction ceiling enforced by the card network before the authorization even reaches your JIT webhook.
Auto-Termination Lifecycle
After a single-use card settles its first transaction:
- Fyatu receives the
CARD_CHARGED (clearing) event from HostFi
TRANSACTION_CLEARED fires to your webhook endpoint- Fyatu immediately calls HostFi to hard-terminate the card
- DB status →
TERMINATED, terminatedBy = SYSTEM
CARD_TERMINATED fires with reason: SINGLE_USE_EXHAUSTED
The gap between TRANSACTION_CLEARED and CARD_TERMINATED is typically under one second.
CARD_TERMINATED Webhook
{
"event": "CARD_TERMINATED",
"eventId": "evt_01HXYZ1122ABCDEF3344",
"businessId": "BUS1A2B3C4D5E6F",
"timestamp": "2026-05-28T10:00:02Z",
"data": {
"cardId": "crd_01HXYZ9999ABCDEF0001",
"status": "TERMINATED",
"cardType": "VIRTUAL",
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"reason": "SINGLE_USE_EXHAUSTED"
}
}
reason: SINGLE_USE_EXHAUSTED distinguishes automatic single-use termination from manual terminations triggered via the API or portal (reason absent or "MANUAL").
JIT Authorization on Single-Use Cards
Single-use cards participate in the full JIT authorization flow. Your CARD_AUTHORIZATION_VERIFY handler receives an extra field:
| Field | Type | Description |
|---|
isOneTimeUse | boolean | true for single-use cards — use this to apply any special approval logic |
Single-Use vs JIT vs Pre-Funded
| Pre-funded | JIT | Single-use |
|---|
| Balance location | On the card | Program ledger | Program ledger |
| Auth decision | Auto-approved | Your server | Your server |
| Max transactions | Unlimited | Unlimited | 1 (then terminates) |
isOneTimeUse | false | false | true |
| Spend limit type | Product-defined | Product-defined | TRANSAMOUNT |
| Best for | Per-employee budgets | Corporate spend | Vendor payments, guest checkout |
Sandbox Testing
In SANDBOX mode, JIT authorizations approve automatically and single-use termination fires normally after the clearing event. You can use the simulation endpoint to test the full lifecycle:
# 1. Issue a single-use card (save cardId)
# 2. Simulate a clearing event
curl -X POST https://api.fyatu.com/webhooks/internal/simulate-hostfi-transaction \
-H "Content-Type: application/json" \
-d '{
"cardRef": "<HostFi card ID>",
"type": "clearing",
"amount": 50.00,
"currency": "USD"
}'
# 3. Check card status — should be TERMINATED within 1 second
Webhook Events Summary
| Event | When it fires |
|---|
CARD_ISSUED | Card created — isOneTimeUse: true in payload |
CARD_AUTHORIZATION_VERIFY | Synchronous JIT auth — includes isOneTimeUse flag |
CARD_AUTHORIZATION | Post-decision authorization record |
TRANSACTION_CLEARED | First transaction settled |
CARD_TERMINATED | Auto-termination complete — reason: SINGLE_USE_EXHAUSTED |
