Transaction Declined

transaction.declined — delivered when a transaction is declined by the card network.

When it fires

A transaction was attempted on one of your cards and the card network refused it. The most
common cause is that the amount exceeds the card's remaining availableLimit.

Because this release performs no pre-authorization, PIK does not participate in the decision;
declineReason is passed through from the card network verbatim.

Declined transactions carry no fees in this release, so fees is empty and
totalFeeAmount is 0.00.

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	Reason passed through from the card network

`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
`convertedAmount`	string	Transaction amount converted at that rate, excluding any fees

Example

{
  "eventId": "evt_01J9X8ZQ4T5S",
  "eventType": "transaction.declined",
  "version": "1.0",
  "occurredAt": "2026-08-11T11:05:02+08:00",
  "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",
      "convertedAmount": "620.00"
    },
    "fees": [],
    "totalFeeAmount": "0.00",
    "totalDebitAmount": "620.00",
    "merchant": {
      "name": "CLOUD HOSTING LTD",
      "mcc": "5734",
      "city": "Singapore",
      "country": "SG"
    },
    "transactionTime": "2026-08-11T11:05:00+08:00",
    "postedTime": null,
    "declineReason": "Insufficient card limit"
  }
}

Verifying the signature

Two headers accompany every delivery:

Header	Value
`x-pik-timestamp`	Unix timestamp in seconds
`x-pik-signature`	HMAC-SHA512 signature, lowercase hex

x-pik-signature = hex_lower( HMAC_SHA512( webhookSecret, rawBody + timestamp ) )

The signed content is the raw body concatenated with the timestamp, no separator.

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

Compare in constant time.

Reject deliveries whose x-pik-timestamp is more than 300 seconds from your clock.

Delivery

Return HTTP 200 within 5 seconds to acknowledge.

Failed deliveries are retried with exponential backoff: 10s, 1m, 5m, 30m, 2h, 6h, 24h.

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#