Skip to main content
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",
    "programId":      "prg_01HXYZ9876ABCDEF0000",
    "cardholderId":   "chl_01HXYZ1234ABCDEF5678",
    "externalId":     "my-user-id-789",
    "type":           "DECLINE",
    "status":         "DECLINED",
    "amountCents":    5000,
    "currency":       "USD",
    "billingAmountCents": 5000,
    "billingCurrency": "USD",
    "exchangeRate":   null,
    "declineReason":  "INSUFFICIENT_BALANCE",
    "merchant": {
      "name":           "Apple Store",
      "id":             "APPLE_MERCHANT_001",
      "city":           "Cupertino",
      "country":        "US",
      "mcc":            "5732",
      "mccDescription": "Electronics Stores"
    }
  }
}

{}

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.

Fires when a cardholder attempts a purchase and the authorization is declined. The 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",
    "programId":      "prg_01HXYZ9876ABCDEF0000",
    "cardholderId":   "chl_01HXYZ1234ABCDEF5678",
    "externalId":     "my-user-id-789",
    "type":           "DECLINE",
    "status":         "DECLINED",
    "amountCents":    5000,
    "currency":       "USD",
    "billingAmountCents": 5000,
    "billingCurrency": "USD",
    "exchangeRate":   null,
    "declineReason":  "INSUFFICIENT_BALANCE",
    "merchant": {
      "name":           "Apple Store",
      "id":             "APPLE_MERCHANT_001",
      "city":           "Cupertino",
      "country":        "US",
      "mcc":            "5732",
      "mccDescription": "Electronics Stores"
    }
  }
}

​
Payload Fields

FieldTypeDescription
transactionIdstringUnique transaction ID for this decline event
typestringAlways DECLINE for this event
statusstringAlways DECLINED for this event
amountCentsintegerAmount that was attempted, in cents
declineReasonstringMachine-readable decline reason — see values below
Decline reason values:
ValueMeaning
INSUFFICIENT_BALANCECard balance too low
CARD_FROZENCard is frozen
CARD_TERMINATEDCard has been terminated
CARDHOLDER_SUSPENDEDCardholder account is suspended
MCC_BLOCKEDMerchant Category Code is blocked for this program
VELOCITY_EXCEEDEDTransaction velocity limit exceeded
FRAUD_SUSPECTEDSuspected fraud — automatic decline
NETWORK_DECLINEDDeclined by the card network
All other fields are the same as 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",
    "programId":      "prg_01HXYZ9876ABCDEF0000",
    "cardholderId":   "chl_01HXYZ1234ABCDEF5678",
    "externalId":     "my-user-id-789",
    "type":           "DECLINE",
    "status":         "DECLINED",
    "amountCents":    5000,
    "currency":       "USD",
    "billingAmountCents": 5000,
    "billingCurrency": "USD",
    "exchangeRate":   null,
    "declineReason":  "INSUFFICIENT_BALANCE",
    "merchant": {
      "name":           "Apple Store",
      "id":             "APPLE_MERCHANT_001",
      "city":           "Cupertino",
      "country":        "US",
      "mcc":            "5732",
      "mccDescription": "Electronics Stores"
    }
  }
}

{}

Authorizations

​
Authorization
string
header
required

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

Body

application/json
​
event
string
Example:

"TRANSACTION_DECLINED"

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

Response

200

Acknowledge the event.