Transaction Completed

transaction.completed — delivered when a purchase, refund or reversal has posted.

When it fires

Whenever a transaction settles against one of your cards. Because card spending happens outside
your control, this webhook is the primary way you learn about transactions — the query API
is for reconciliation and backfill, not for discovery.

Refunds and reversals carry originalTransactionNo pointing at the transaction being reversed.

Payload

Envelope

Field	Type	Description
`eventId`	string	Unique per event. Deduplicate on this value
`eventType`	string	Always `transaction.completed`
`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	`COMPLETED` for this event
`originalTransactionNo`	string	Set on refunds and reversals, otherwise `null`
`transactionAmount`	string	Amount in the merchant's currency
`transactionCurrency`	string	Merchant currency, ISO 4217
`billingAmount`	string	Amount posted in the card's settlement currency
`billingCurrency`	string	Settlement currency, ISO 4217
`fx`	object	Foreign exchange details, see below
`fees`	array	Itemised fee breakdown, see below
`totalFeeAmount`	string	Sum of all fee amounts
`totalDebitAmount`	string	`billingAmount` + `totalFeeAmount`
`merchant`	object	`name` / `mcc` / `city` / `country`
`transactionTime`	string	Time the transaction occurred
`postedTime`	string	Time the transaction was posted
`declineReason`	string	`null` for this event

`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

`fees[]`

Field	Type	Description
`feeCode`	string	`TRANSACTION_FEE` / `FX_CONVERSION_FEE` / `ATM_WITHDRAWAL_FEE` / `CARD_ISSUE_FEE`
`feeName`	string	Human-readable fee name
`amount`	string	Fee amount
`currency`	string	Fee currency
`baseAmount`	string	The amount the fee was calculated on
`calcMode`	string	`PERCENT` / `FIXED` / `MIXED`
`rate`	string	Rate applied for `PERCENT` and `MIXED`
`fixedAmount`	string	Fixed component for `FIXED` and `MIXED`
`minFee` / `maxFee`	string	Bounds applied, `null` when unbounded
`ruleNo` / `ruleVersion`	string / integer	Identifies the exact pricing rule, for reconciliation

Why baseAmount is not billingAmount. On cross-currency transactions billingAmount is
the figure the card network posts, and it can include network-side surcharges on top of the
conversion. Percentage fees are therefore calculated on fx.convertedAmount — the converted
amount with no fees folded in.

Example — cross-currency purchase

{
  "eventId": "evt_01J9X8ZQ4T3P",
  "eventType": "transaction.completed",
  "version": "1.0",
  "occurredAt": "2026-08-11T10:20:18+08:00",
  "data": {
    "transactionNo": "TX260811K3M5N1",
    "cardNo": "CD260811X9Y8Z7",
    "cardholderNo": "CH260811A1B2C3",
    "type": "PURCHASE",
    "status": "COMPLETED",
    "originalTransactionNo": null,
    "transactionAmount": "10.00",
    "transactionCurrency": "EUR",
    "billingAmount": "13.10",
    "billingCurrency": "USD",
    "fx": {
      "isCrossCurrency": true,
      "rate": "1.160000",
      "convertedAmount": "11.60"
    },
    "fees": [
      {
        "feeCode": "TRANSACTION_FEE",
        "feeName": "Transaction Fee",
        "amount": "0.12",
        "currency": "USD",
        "baseAmount": "11.60",
        "calcMode": "PERCENT",
        "rate": "0.010000",
        "fixedAmount": "0.00",
        "minFee": null,
        "maxFee": null,
        "ruleNo": "FR-TXN-0001",
        "ruleVersion": 2
      },
      {
        "feeCode": "FX_CONVERSION_FEE",
        "feeName": "FX Conversion Fee",
        "amount": "0.02",
        "currency": "USD",
        "baseAmount": "11.60",
        "calcMode": "PERCENT",
        "rate": "0.002000",
        "fixedAmount": "0.00",
        "minFee": "0.01",
        "maxFee": null,
        "ruleNo": "FR-FX-0001",
        "ruleVersion": 3
      }
    ],
    "totalFeeAmount": "0.14",
    "totalDebitAmount": "13.24",
    "merchant": {
      "name": "STEAM PURCHASE",
      "mcc": "5734",
      "city": "Singapore",
      "country": "SG"
    },
    "transactionTime": "2026-08-11T10:20:15+08:00",
    "postedTime": "2026-08-11T10:20:18+08:00",
    "declineReason": null
  }
}

Example — refund

{
  "eventId": "evt_01J9X8ZQ4T4R",
  "eventType": "transaction.completed",
  "version": "1.0",
  "occurredAt": "2026-08-12T09:02:11+08:00",
  "data": {
    "transactionNo": "TX260812P7Q2R8",
    "cardNo": "CD260811X9Y8Z7",
    "cardholderNo": "CH260811A1B2C3",
    "type": "REFUND",
    "status": "COMPLETED",
    "originalTransactionNo": "TX260811K3M5N1",
    "transactionAmount": "10.00",
    "transactionCurrency": "EUR",
    "billingAmount": "13.10",
    "billingCurrency": "USD",
    "fx": {
      "isCrossCurrency": true,
      "rate": "1.160000",
      "convertedAmount": "11.60"
    },
    "fees": [],
    "totalFeeAmount": "0.00",
    "totalDebitAmount": "13.10",
    "merchant": {
      "name": "STEAM PURCHASE",
      "mcc": "5734",
      "city": "Singapore",
      "country": "SG"
    },
    "transactionTime": "2026-08-12T09:02:08+08:00",
    "postedTime": "2026-08-12T09:02:11+08:00",
    "declineReason": null
  }
}

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.

Treat transactionNo as the business key; a transaction can generate several events.

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

Transaction Completed

When it fires#

Payload#

Envelope#

data#

fx#

fees[]#

Example — cross-currency purchase#

Example — refund#

Verifying the signature#

Delivery#