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_BALANCE",
    "authorizationCode": "A1B2C3",
    "merchant": {
      "name":           "Apple Store",
      "id":             "APPLE_MERCHANT_001",
      "city":           "Cupertino",
      "country":        "US",
      "mcc":            "5732",
      "mccDescription": "Electronics Stores"
    }
  }
}

{}

WEBHOOK

{
  "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_BALANCE",
    "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 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_BALANCE",
    "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

Decline reason values:

Value	Meaning
`INSUFFICIENT_BALANCE`	Card balance too low
`CARD_FROZEN`	Card is frozen
`CARD_TERMINATED`	Card has been terminated
`CARDHOLDER_SUSPENDED`	Cardholder account is suspended
`MCC_BLOCKED`	Merchant Category Code is blocked for this program
`VELOCITY_EXCEEDED`	Transaction velocity limit exceeded
`FRAUD_SUSPECTED`	Suspected fraud — automatic decline
`NETWORK_DECLINED`	Declined 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",
    "cardholderId":   "chl_01HXYZ1234ABCDEF5678",
    "externalId":     "my-user-id-789",
    "type":           "AUTHORIZATION",
    "status":         "DECLINED",
    "amount":         50.00,
    "currency":       "USD",
    "billingAmount":  50.00,
    "billingCurrency": "USD",
    "declineReason":  "INSUFFICIENT_BALANCE",
    "authorizationCode": "A1B2C3",
    "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

Show child attributes

Response

200

Acknowledge the event.

Guides

JIT Authorization

Card Events

Transaction Events

Cardholder Events

Account Events

Billing Events

Event Type

Payload

Payload Fields

Common Use Cases

Authorizations

Body

Response

​Event Type

​Payload

​Payload Fields

​Common Use Cases

Authorizations

Body

Response

Event Type

Payload

Payload Fields

Common Use Cases