{
"event": "TRANSACTION_DECLINED",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-05-22T10:00:00Z",
"data": {
"transactionId": "txn_01HXYZ5555ABCDEF9999",
"cardId": "crd_01HXYZ5555ABCDEF1111",
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"externalId": "my-user-id-789",
"type": "AUTHORIZATION",
"status": "DECLINED",
"amount": 50.00,
"currency": "USD",
"billingAmount": 50.00,
"billingCurrency": "USD",
"declineReason": "INSUFFICIENT_FUNDS",
"authorizationCode": "A1B2C3",
"merchant": {
"name": "Apple Store",
"id": "APPLE_MERCHANT_001",
"city": "Cupertino",
"country": "US",
"mcc": "5732",
"mccDescription": "Electronics Stores"
}
}
}
{}
Transaction Events
TRANSACTION_DECLINED
Fired when a card authorization is declined. No funds are moved.
WEBHOOK
TRANSACTION_DECLINED
{
"event": "TRANSACTION_DECLINED",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-05-22T10:00:00Z",
"data": {
"transactionId": "txn_01HXYZ5555ABCDEF9999",
"cardId": "crd_01HXYZ5555ABCDEF1111",
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"externalId": "my-user-id-789",
"type": "AUTHORIZATION",
"status": "DECLINED",
"amount": 50.00,
"currency": "USD",
"billingAmount": 50.00,
"billingCurrency": "USD",
"declineReason": "INSUFFICIENT_FUNDS",
"authorizationCode": "A1B2C3",
"merchant": {
"name": "Apple Store",
"id": "APPLE_MERCHANT_001",
"city": "Cupertino",
"country": "US",
"mcc": "5732",
"mccDescription": "Electronics Stores"
}
}
}
{}
Fires when a cardholder attempts a purchase and the authorization is declined. The
Decline reason values:
All other fields are the same as
declineReason field explains why. No funds are moved on a decline.
Event Type
TRANSACTION_DECLINED
Payload
{
"event": "TRANSACTION_DECLINED",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-05-22T10:00:00Z",
"data": {
"transactionId": "txn_01HXYZ5555ABCDEF9999",
"cardId": "crd_01HXYZ5555ABCDEF1111",
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"externalId": "my-user-id-789",
"type": "AUTHORIZATION",
"status": "DECLINED",
"amount": 50.00,
"currency": "USD",
"billingAmount": 50.00,
"billingCurrency": "USD",
"declineReason": "INSUFFICIENT_FUNDS",
"authorizationCode": "A1B2C3",
"merchant": {
"name": "Apple Store",
"id": "APPLE_MERCHANT_001",
"city": "Cupertino",
"country": "US",
"mcc": "5732",
"mccDescription": "Electronics Stores"
}
}
}
Payload Fields
| Field | Type | Description |
|---|---|---|
transactionId | string | Unique transaction ID for this decline event |
type | string | Always AUTHORIZATION for this event |
status | string | Always DECLINED for this event |
amount | number | Amount that was attempted, in dollars |
declineReason | string | Machine-readable decline reason — see values below |
authorizationCode | string | Network authorization code for the declined attempt — the same field carried by TRANSACTION_AUTHORIZED/TRANSACTION_CLEARED. Use it to correlate a decline with your own records and with any resulting decline fee (TRANSACTION_FEE) that shares it. Present when the card network supplies one |
declineReason is a machine-readable code. Known values:
| Value | Meaning |
|---|---|
INSUFFICIENT_FUNDS | Card balance too low |
BLOCKED_MCC | Merchant Category Code is blocked for this program |
CARD_NOT_ACTIVE | Card is not active (frozen, terminated, or not yet activated) |
SPEND_LIMIT_EXCEEDED | Spend/velocity limit exceeded |
INVALID_PIN | Incorrect PIN |
CARD_EXPIRED | Card has expired |
DO_NOT_HONOR | Generic issuer decline |
TRANSACTION_NOT_PERMITTED | Transaction type not permitted on this card |
RESTRICTED_CARD | Card is restricted |
SECURITY_VIOLATION | Security violation detected |
UNKNOWN_DECLINE | Reason not mapped to a known code (fallback) |
Any provider reason that does not map to one of the codes above is normalised to
UNKNOWN_DECLINE. Always handle UNKNOWN_DECLINE as a catch-all.TRANSACTION_AUTHORIZED. See Transaction Events for the full field reference.
Common Use Cases
- Send a real-time decline notification to the cardholder
- Log decline patterns to detect fraud or misconfiguration
- Prompt the cardholder to top up their card if
INSUFFICIENT_BALANCE
{
"event": "TRANSACTION_DECLINED",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-05-22T10:00:00Z",
"data": {
"transactionId": "txn_01HXYZ5555ABCDEF9999",
"cardId": "crd_01HXYZ5555ABCDEF1111",
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"externalId": "my-user-id-789",
"type": "AUTHORIZATION",
"status": "DECLINED",
"amount": 50.00,
"currency": "USD",
"billingAmount": 50.00,
"billingCurrency": "USD",
"declineReason": "INSUFFICIENT_FUNDS",
"authorizationCode": "A1B2C3",
"merchant": {
"name": "Apple Store",
"id": "APPLE_MERCHANT_001",
"city": "Cupertino",
"country": "US",
"mcc": "5732",
"mccDescription": "Electronics Stores"
}
}
}
{}
Authorizations
API key from the FYATU CaaS portal. Pass as Authorization: Bearer <key>.
Body
application/json
Response
200
Acknowledge the event.