Payments API events
Payment lifecycle events delivered to Payments API webhook endpoints.
Payments API events track the lifecycle of a transaction attempt from creation
through its initial outcome, and then any later refund, chargeback, or
confirmed-fraud updates for the resulting payment record. 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 transaction attempt 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 checkout attempt could not complete normally, for example because of a timeout or incomplete authentication. This does not confirm that no authorisation or issuer hold occurred. |
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. |
Lifecycle Diagrams
Payments API webhook events span two public phases: the initial transaction attempt outcome, and any later lifecycle updates on the resulting payment record.
Initial transaction attempt
Follow-up after payment.success
data payload
Payment events carry a data object with a stable core set of fields. The
exact shape depends on whether WiPay has already created the completed payment
record for that transaction attempt. For lifecycle automation, use the envelope
event as the primary signal. data.status is a coarse status snapshot, while
data.status_desc provides the more specific human-readable lifecycle state.
Inside the webhook envelope, data.data echoes the optional request-time pass-through data.
| 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 | Integrator-supplied pass-through string. |
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 snapshot. Values are pending, success, failed, error, or incomplete. |
status_desc | string | Human-readable lifecycle 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 created the completed payment record for the transaction
attempt (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"
}Interpreting payment state
- Use the envelope
eventfor the payment lifecycle outcome anddata.statusas a coarse payment-status snapshot. They are not interchangeable. - Both
payment.failedandpayment.errorcan carrydata.status: "failed". Do not requiredata.status: "error"when receivingpayment.error. data.status_descdescribes the payment's lifecycle state.Normalcan accompany either a successful or an unsuccessful payment; it is not an approval indicator. Never usestatus_descalone to decide whether to fulfil an order.payment.createdis an intermediate event. It means WiPay has accepted the transaction attempt and is still determining the initial result.payment.success,payment.failed, andpayment.errorclose the initial checkout attempt. A failed or errored attempt does not promise a laterpayment.successor another automatic outcome event.pendingandincompleteappear only indata.status. They are not event names.pendingmeans the transaction attempt is still being processed.incompletemeans WiPay has a transaction attempt on file but no completed payment record yet, and the attempt is not currently classified as pending.- Later events such as
payment.refund_requested,payment.refunded,payment.chargeback_pending,payment.chargeback_processed,payment.chargeback_released, andpayment.fraud_confirmedare follow-up lifecycle updates on the resulting payment record. On those events,data.statusmay still besuccess; useeventanddata.status_descfor the specific meaning.
Reconciliation and replacement checkouts
A webhook contains the state at the time of the event. Retrieve
Transaction returns the current state
for a transaction owned by the authenticated account. Later lifecycle changes
can therefore make Retrieve differ from an earlier webhook. The combination
event: "payment.error" and data.status: "failed" is not, by itself, evidence
of delayed processing.
Do not fulfil an order for an unsuccessful or unresolved attempt. If a timeout, an apparent card charge, or conflicting results leave the financial outcome uncertain, retain the transaction reference and contact WiPay for reconciliation before submitting a replacement checkout. There is no fixed polling delay after which an unresolved error guarantees that no authorisation or issuer hold exists. The webhook delivery retry window is not a payment-resolution deadline.
A replacement checkout is a new payment attempt. Reusing an order_id does
not guarantee that another charge will be prevented. Track each
transaction_id against the order, prevent concurrent checkout attempts, and
ensure the order is fulfilled or credited at most once.
Verify and durably accept valid unsuccessful-payment events, then acknowledge them using the shared delivery model. Payment reconciliation must not depend on repeatedly rejecting the same webhook.
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"
}
}