Webhooks
Payments API events
Payment lifecycle events delivered to Payments API webhook endpoints.
Payments API events track the lifecycle of a payment from creation through
authorisation, refunds, chargebacks, and confirmed fraud outcomes. Every event
uses the shared webhook envelope, headers, signature, and retry model.
Use the envelope event as the authoritative lifecycle signal.
Event catalog
| Event | When it fires |
|---|---|
payment.created | A payment request has been created and is awaiting processing. |
payment.success | The payment was authorised and captured successfully. |
payment.failed | The payment was declined by the issuer or gateway. |
payment.error | The payment attempt errored before a definitive outcome (e.g. gateway timeout). |
payment.chargeback_pending | A chargeback has been raised and the transaction is held pending review. |
payment.chargeback_processed | Funds have been taken to cover a confirmed chargeback. |
payment.chargeback_released | A pending chargeback has been released; funds are no longer held. |
payment.refund_requested | A refund has been requested on a completed transaction. |
payment.refunded | A refund has been processed and funds returned to the payer. |
payment.refund_rejected | A refund request has been rejected. meta.reason carries the decision reason. |
payment.fraud_confirmed | The transaction has been confirmed as fraud and funds taken. |
data payload
Payment events carry a data object with a stable core set of fields. The
exact shape depends on whether WiPay already has a completed transaction for
the payment. For lifecycle automation, use the envelope event as the primary
signal. data.status is the general payment status, while data.status_desc
provides the human-readable transaction state.
| Field | Type | Notes |
|---|---|---|
card | string | null | Masked PAN, e.g. XXXXXXXXXXXX1234. |
currency | string | ISO 4217 alpha code of the amount the merchant is charged in. |
currency_credited | string | ISO 4217 alpha code of the amount the merchant is credited in. May differ when cross-currency settlement applies. |
customer_address | string | null | As supplied at request time. |
customer_email | string | null | As supplied at request time. |
customer_name | string | null | As supplied at request time. |
customer_phone | string | null | As supplied at request time. |
data | string | null | Merchant-supplied pass-through value. |
date | string | ISO 8601 timestamp of the transaction creation. |
fee_structure | string | Display name: Customer Pay, Merchant Absorb, or Split. |
hash | string | null | Merchant-supplied hash echoed back. |
message | string | null | Gateway response message. |
order_id | string | null | Merchant-supplied order identifier. |
origin | string | Channel/origin label, e.g. card purchase. |
receiver | string | Merchant business / receiver name. |
status | string | General payment status. Values are pending, success, failed, error, or incomplete. |
status_desc | string | Human-readable transaction state. For post-authorisation lifecycle events this is often more specific than status, for example Refund Requested or Taken for Chargeback. |
total | string | 2-decimal amount the merchant is charged. |
total_credited | string | 2-decimal amount the merchant is credited. |
transaction_id | string | WiPay transaction reference, e.g. CB-4778D2C4. |
Before WiPay has a completed transaction record for the payment (for example on
an early payment.created delivery), a reduced shape is sent that omits
gateway-supplied fields:
{
"currency": "TTD",
"data": "{\"cart_id\":\"cart_123\"}",
"date": "2026-04-17T19:14:25+00:00",
"fee_structure": "Customer Pay",
"order_id": "ORDER-0001",
"status": "pending",
"status_desc": "Transaction Processing",
"total": "25.00",
"transaction_id": "CB-4778D2C4"
}meta
meta carries context that isn't part of the payment object itself:
| Key | Events | Description |
|---|---|---|
transaction_id | All payment events | The merchant-facing transaction reference. Always mirrored here for convenience. |
previous_status | Status-change events (payment.refund_requested, payment.refunded, payment.chargeback_pending, payment.chargeback_processed, payment.fraud_confirmed) | Previous transaction-state value before the transition. Treat this as an opaque integer for correlation only; use event and data.status_desc for workflow logic. |
reason | payment.refund_rejected | Human-readable rejection reason. |
Additional metadata keys may be present on specific events. Ignore keys you do not use.
Example — payment.success
{
"id": "3e1f9b2c-7d0a-4a68-9b74-2b4e1c9a4a1e",
"api_family": "payments_api",
"event": "payment.success",
"occurred_at": "2026-04-17T19:14:25+00:00",
"data": {
"card": "XXXXXXXXXXXX1234",
"currency": "TTD",
"currency_credited": "TTD",
"customer_address": "1 Example Avenue, Port of Spain",
"customer_email": "jane.customer@example.com",
"customer_name": "Jane Customer",
"customer_phone": "+18680000000",
"data": null,
"date": "2026-04-17T19:14:25+00:00",
"fee_structure": "Customer Pay",
"hash": "9f3a8c0b1d2e4f5a6b7c8d9e0f1a2b3c",
"message": "Approved or completed successfully",
"order_id": "ORDER-0001",
"origin": "card purchase",
"receiver": "John Merchant",
"status": "success",
"status_desc": "Normal",
"total": "25.00",
"total_credited": "25.00",
"transaction_id": "CB-4778D2C4"
},
"meta": {
"transaction_id": "CB-4778D2C4"
}
}Example — payment.refund_requested
{
"id": "5b2c8d4e-1a3f-4d7c-9e0b-2c4d6e8f0a1b",
"api_family": "payments_api",
"event": "payment.refund_requested",
"occurred_at": "2026-04-17T20:02:11+00:00",
"data": {
"card": "XXXXXXXXXXXX1234",
"currency": "TTD",
"currency_credited": "TTD",
"customer_email": "jane.customer@example.com",
"customer_name": "Jane Customer",
"date": "2026-04-17T19:14:25+00:00",
"fee_structure": "Customer Pay",
"message": "Approved or completed successfully",
"order_id": "ORDER-0001",
"origin": "card purchase",
"receiver": "John Merchant",
"status": "success",
"status_desc": "Refund Requested",
"total": "25.00",
"total_credited": "25.00",
"transaction_id": "CB-4778D2C4"
},
"meta": {
"previous_status": 0,
"transaction_id": "CB-4778D2C4"
}
}Example — payment.refund_rejected
{
"id": "7d4e0f6a-3b5d-4c9e-a1b2-c3d4e5f60718",
"api_family": "payments_api",
"event": "payment.refund_rejected",
"occurred_at": "2026-04-18T09:30:00+00:00",
"data": {
"card": "XXXXXXXXXXXX1234",
"currency": "TTD",
"currency_credited": "TTD",
"date": "2026-04-17T19:14:25+00:00",
"fee_structure": "Customer Pay",
"order_id": "ORDER-0001",
"origin": "card purchase",
"receiver": "John Merchant",
"status": "success",
"status_desc": "Normal",
"total": "25.00",
"total_credited": "25.00",
"transaction_id": "CB-4778D2C4"
},
"meta": {
"reason": "Refund window has elapsed.",
"transaction_id": "CB-4778D2C4"
}
}