Transaction Declined

transaction.declined — delivered when a transaction on one of your cards is declined.

When it fires

A transaction was attempted on one of your cards and was refused. It can be refused at three
points:

By PIK's authorisation decision — for example your USD balance does not cover the amount
plus fees, the card is not ACTIVE, or the transaction is not in USD.

By your decision endpoint, if you have enabled authorization decisions,
including when it did not answer in time.

By the card network — for example the amount exceeds the card's remaining availableLimit.

declineReason is a human-readable explanation for display and support; do not parse it.

Declined transactions carry no fees and move no money, so fees is empty and
totalFeeAmount is 0.00. Any amount held on your balance for the attempt is released.

Payload

Envelope

Field	Type	Description
`eventId`	string	Unique per event. Deduplicate on this value
`eventType`	string	Always `transaction.declined`
`version`	string	Payload schema version. Additive changes do not bump it
`occurredAt`	string	When the event happened, not when it was delivered (ISO 8601)
`data`	object	The transaction, see below

`data`

Structurally identical to the response of GET /api/v1/issuing/transaction/{transactionNo}, so
a single parser handles both paths.

Field	Type	Description
`transactionNo`	string	PIK transaction number
`cardNo`	string	PIK card number
`cardholderNo`	string	PIK cardholder number
`type`	string	`PURCHASE` / `REFUND` / `REVERSAL` / `ATM_WITHDRAWAL` / `VERIFICATION` / `SETTLEMENT_ADJUST`
`status`	string	`DECLINED` for this event
`originalTransactionNo`	string	`null` unless the declined attempt referenced an earlier transaction
`transactionAmount`	string	Amount in the merchant's currency
`transactionCurrency`	string	Merchant currency, ISO 4217
`billingAmount`	string	Amount that would have been posted in the settlement currency
`billingCurrency`	string	Settlement currency, ISO 4217
`fx`	object	Foreign exchange details, see below
`fees`	array	Empty for declined transactions
`totalFeeAmount`	string	`0.00`
`totalDebitAmount`	string	Equals `billingAmount`, since no fee applies
`merchant`	object	`name` / `mcc` / `city` / `country`
`transactionTime`	string	Time the transaction was attempted
`postedTime`	string	`null` — the transaction never posted
`declineReason`	string	Human-readable reason, for display and support. Do not parse it

`fx`

Field	Type	Description
`isCrossCurrency`	boolean	Whether the transaction currency differs from the billing currency
`rate`	string	Exchange rate applied, billing currency per unit of transaction currency

Example

{
  "eventId": "evt_01J9X8ZQ4T5S",
  "eventType": "transaction.declined",
  "version": "1.0",
  "occurredAt": "2026-08-11T03:05:02Z",
  "data": {
    "transactionNo": "TX260811V4W6X2",
    "cardNo": "CD260811X9Y8Z7",
    "cardholderNo": "CH260811A1B2C3",
    "type": "PURCHASE",
    "status": "DECLINED",
    "originalTransactionNo": null,
    "transactionAmount": "620.00",
    "transactionCurrency": "USD",
    "billingAmount": "620.00",
    "billingCurrency": "USD",
    "fx": {
      "isCrossCurrency": false,
      "rate": "1.00000000"
    },
    "fees": [],
    "totalFeeAmount": "0.00",
    "totalDebitAmount": "620.00",
    "merchant": {
      "name": "CLOUD HOSTING LTD",
      "mcc": "5734",
      "city": "Singapore",
      "country": "SG"
    },
    "transactionTime": "2026-08-11T03:05:00Z",
    "postedTime": null,
    "declineReason": "Insufficient card limit"
  }
}

Verifying the signature

Three headers accompany every delivery:

Header	Value
`X-Webhook-Event`	Event category, always `ISSUING` for this event
`X-Webhook-Event-Type`	The specific event type, see above
`X-Webhook-Signature`	HMAC-SHA256 signature, lowercase hex

X-Webhook-Signature = hex_lower( HMAC_SHA256( appSecret, rawBody ) )

The signed content is the raw request body only, with no timestamp and no separator. The signing
key is your appSecret — there is no separate webhook secret.

Sign the raw bytes of the request body, before any JSON parsing.

Compare in constant time.

Nothing time-based is signed, so a captured delivery stays replayable — deduplicating on
eventId is mandatory, not optional.

Delivery

Return any 2xx within 10 seconds to acknowledge.

Failed deliveries are retried on a fixed interval: 5 attempts, 5 minutes apart (about
20 minutes in total), after which the event is marked exhausted and never retried again.

This endpoint receives Issuing events only; still return 2xx for event types you do not handle.

Delivery is at least once — deduplicate on eventId.

Ordering is not guaranteed — use occurredAt to decide which version is newer.

See the Webhooks guide for verification code samples and recommended
handling.

Transaction Declined

When it fires#

Payload#

Envelope#

data#

fx#

Example#

Verifying the signature#

Delivery#