Skip to main content
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.
You must respond within 1.2 seconds. If your endpoint does not respond in time, Fyatu automatically approves the request (fail-open). Design your handler to be fast — do not call slow external services in the critical path.

Event Type


When It Fires

This event fires for two distinct actions, distinguished by the type field in data: Both require the same response format from your server.

Payload

Payload Fields

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.
Similarly, if the card is FROZEN or TERMINATED, Fyatu declines automatically and does not forward the request to you.

Your Response

Respond with HTTP 200 and a JSON body. The decision field is required for both action types.

Approve

Decline

Response Fields

Decline Reason Codes

If you return an unrecognised reason code, Fyatu substitutes DO_NOT_HONOUR.

What Happens After Your Response

Purchase (type: AUTHORIZATION)

Tokenization (type: AUTHORIZATION_VERIFY)


Timeout and Fallback Behaviour

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 (freeze, terminate) — do not rely solely on this webhook.

Example Handler


Authorizations

Authorization
string
header
required

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

Body

application/json
event
string
Example:

"CARD_AUTHORIZATION_VERIFY"

eventId
string
businessId
string
environment
enum<string>
Available options:
LIVE,
SANDBOX
timestamp
string<date-time>
data
object

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.

decision
enum<string>
required

APPROVE to allow the transaction; DECLINE to block it.

Available options:
APPROVE,
DECLINE
reason
enum<string>

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