WiPay
Webhooks

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

EventWhen it fires
payment.createdA transaction attempt has been created and is awaiting processing.
payment.successThe payment was authorised and captured successfully.
payment.failedThe payment was declined by the issuer or gateway.
payment.errorThe 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_pendingA chargeback has been raised and the transaction is held pending review.
payment.chargeback_processedFunds have been taken to cover a confirmed chargeback.
payment.chargeback_releasedA pending chargeback has been released; funds are no longer held.
payment.refund_requestedA refund has been requested on a completed transaction.
payment.refundedA refund has been processed and funds returned to the payer.
payment.refund_rejectedA refund request has been rejected. meta.reason carries the decision reason.
payment.fraud_confirmedThe 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.

FieldTypeNotes
cardstring | nullMasked PAN, e.g. XXXXXXXXXXXX1234.
currencystringISO 4217 alpha code of the amount the merchant is charged in.
currency_creditedstringISO 4217 alpha code of the amount the merchant is credited in. May differ when cross-currency settlement applies.
customer_addressstring | nullAs supplied at request time.
customer_emailstring | nullAs supplied at request time.
customer_namestring | nullAs supplied at request time.
customer_phonestring | nullAs supplied at request time.
datastring | nullIntegrator-supplied pass-through string.
datestringISO 8601 timestamp of the transaction creation.
fee_structurestringDisplay name: Customer Pay, Merchant Absorb, or Split.
hashstring | nullMerchant-supplied hash echoed back.
messagestring | nullGateway response message.
order_idstring | nullMerchant-supplied order identifier.
originstringChannel/origin label, e.g. card purchase.
receiverstringMerchant business / receiver name.
statusstringGeneral payment-status snapshot. Values are pending, success, failed, error, or incomplete.
status_descstringHuman-readable lifecycle state. For post-authorisation lifecycle events this is often more specific than status, for example Refund Requested or Taken for Chargeback.
totalstring2-decimal amount the merchant is charged.
total_creditedstring2-decimal amount the merchant is credited.
transaction_idstringWiPay 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 event for the payment lifecycle outcome and data.status as a coarse payment-status snapshot. They are not interchangeable.
  • Both payment.failed and payment.error can carry data.status: "failed". Do not require data.status: "error" when receiving payment.error.
  • data.status_desc describes the payment's lifecycle state. Normal can accompany either a successful or an unsuccessful payment; it is not an approval indicator. Never use status_desc alone to decide whether to fulfil an order.
  • 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 checkout attempt. A failed or errored attempt does not promise a later payment.success or another automatic outcome event.
  • 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.

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:

KeyEventsDescription
transaction_idAll payment eventsThe merchant-facing transaction reference. Always mirrored here for convenience.
previous_statusStatus-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.
reasonpayment.refund_rejectedHuman-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"
  }
}