JIT Authorization
CARD_AUTHORIZATION_VERIFY
Synchronous authorization request sent to your webhook for every JIT card event. Your response controls whether the action is approved or declined.
WEBHOOK
Fires synchronously whenever a cardholder action requires your approval. Fyatu forwards the request to your registered endpoint and waits up to 1.2 seconds for your APPROVE or DECLINE response. Your decision is sent back to the card network immediately — the cardholder experiences no perceptible delay.
Both require the same response format from your server.
If you return an unrecognised reason code, Fyatu substitutes
Failing open is intentional. An unexpected approval is recoverable — you can investigate after the fact. An unexpected decline silently blocks a legitimate cardholder action and is not recoverable.
If you need guaranteed blocking for a card (e.g. a terminated cardholder), use the card lifecycle endpoints (
Event Type
When It Fires
This event fires for two distinct actions, distinguished by thetype field in data:
data.type | What it means | Fyatu balance gate |
|---|---|---|
AUTHORIZATION | A cardholder is making a purchase (JIT charge) | Yes — program balance must be ≥ amount + feeAmount. Fyatu auto-declines if insufficient and does not call your endpoint. |
AUTHORIZATION_VERIFY | A cardholder is adding their card to Apple Pay or Google Pay (tokenization) | Yes — program balance must be ≥ $1.00. Fyatu auto-declines if insufficient and does not call your endpoint. |
Payload
Payload Fields
| Field | Type | Description |
|---|---|---|
type | string | AUTHORIZATION for a purchase, AUTHORIZATION_VERIFY for card tokenization (Apple/Google Pay) |
cardId | string | The card being used |
cardholderId | string | The cardholder who holds the card |
amount | number | Amount in dollars. 0.00 for tokenization events |
feeAmount | number | Network or cross-border fee in dollars. 0.00 for tokenization events |
currency | string | Authorization currency (ISO 4217) |
merchantName | string | Merchant name from the card network |
merchantMcc | string | Merchant Category Code (ISO 18245). Empty string if not provided by the network |
merchantCountry | string | Two-letter country code where the merchant is located. Empty string if not provided |
isOneTimeUse | boolean | Whether the card is configured for single use |
timestamp | string | ISO 8601 timestamp of the authorization request |
Fyatu applies a balance gate before calling your endpoint — your endpoint is never called if the gate fails.
AUTHORIZATION: program balance must be ≥amount + feeAmount. On approval, that amount is reserved from your ledger.AUTHORIZATION_VERIFY: program balance must be ≥ $1.00 to confirm the program is funded before a card is tokenized.
FROZEN or TERMINATED, Fyatu declines automatically and does not forward the request to you.Your Response
Respond with HTTP200 and a JSON body. The decision field is required for both action types.
Approve
Decline
Response Fields
| Field | Type | Required | Description |
|---|---|---|---|
decision | string | Yes | "APPROVE" or "DECLINE" |
reason | string | No | Decline reason code. Ignored when decision is "APPROVE" |
Decline Reason Codes
| Code | When to use |
|---|---|
VELOCITY_EXCEED | Spending limit exceeded |
INVALID_MERCHANT | Merchant is not permitted for this program |
BLK_MRCH | Merchant is on your blocked list |
TXN_NOT_PERMIT | This transaction type is not allowed |
SUSPECT_FRAUD | Transaction flagged as suspicious |
RESTRICTED | Card is suspended or access is restricted |
CASH_REQ_EXCEED | Cash withdrawal limit exceeded |
DO_NOT_HONOUR | Generic decline — use when no specific code applies |
DO_NOT_HONOUR.
What Happens After Your Response
Purchase (type: AUTHORIZATION)
Tokenization (type: AUTHORIZATION_VERIFY)
Timeout and Fallback Behaviour
| Scenario | Fyatu’s action |
|---|---|
Card is FROZEN or TERMINATED | Auto-decline — your endpoint is not called |
AUTHORIZATION: program balance < amount + feeAmount | Auto-decline — your endpoint is not called |
AUTHORIZATION_VERIFY: program balance < $1.00 | Auto-decline — your endpoint is not called |
Your endpoint responds {"decision": "APPROVE"} within 1.2 s | Action approved |
Your endpoint responds {"decision": "DECLINE", ...} within 1.2 s | Action declined |
No CARD_AUTHORIZATION_VERIFY endpoint registered | Auto-approve (fail-open) |
| Endpoint does not respond within 1.2 s | Auto-approve (fail-open) |
| Endpoint returns non-2xx HTTP status | Auto-approve (fail-open) |
| Response body cannot be parsed | Auto-approve (fail-open) |
freeze, terminate) — do not rely solely on this webhook.
Example Handler
Related Events
| Event | When it fires |
|---|---|
TRANSACTION_AUTHORIZED | Authorization confirmed by the card network after your APPROVE |
TRANSACTION_CLEARED | Transaction fully settled |
TRANSACTION_DECLINED | Authorization declined (by you or by Fyatu) |
ACCOUNT_LOW_BALANCE | Program balance dropped below your configured threshold |
Authorizations
API key from the FYATU CaaS portal. Pass as Authorization: Bearer <key>.
Body
application/json
Response
200 - application/json
Your authorization decision. Return this within 1 second. If your endpoint times out or returns a non-2xx status, Fyatu auto-approves.
APPROVE to allow the transaction; DECLINE to block it.
Available options:
APPROVE, DECLINE Optional decline reason code. Ignored when decision is APPROVE.
Available options:
VELOCITY_EXCEED, INVALID_MERCHANT, BLK_MRCH, TXN_NOT_PERMIT, SUSPECT_FRAUD, RESTRICTED, CASH_REQ_EXCEED, DO_NOT_HONOUR 
