Payments API events

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 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.

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 data.status as a coarse snapshot of the transaction attempt or payment record.
Use data.status_desc for the more specific human-readable lifecycle state.
payment.created is an intermediate event. It means WiPay has accepted the transaction attempt and is still determining the initial result.
payment.success, payment.failed, and payment.error close the initial transaction attempt.
pending and incomplete appear only in data.status. They are not event names.
pending means the transaction attempt is still being processed.
incomplete means 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, and payment.fraud_confirmed are follow-up lifecycle updates on the resulting payment record. On those events, data.status may still be success; use event and data.status_desc for the specific meaning.

`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"
  }
}

Payments API events

On this page