Payment notify events

Use notify events for lightweight lifecycle signals during a Checkout payment flow.

Notify events are not the same as request-level callbacks:

notify = event-style lifecycle updates
callback = full request-level transaction snapshot

What a notify event represents

A notify event carries a specific lifecycle signal such as:

payment_initiated
payment_completed
payee_payment_completed

The current docs contract is intentionally lighter and more permissive than the callback contract because exact provider edge variants are still being expanded in retained fixtures.

Event envelope

Current notify events require:

event_type
transaction_id
status
timestamp
description

Each notify event must also include at least one of:

payer
payee

Payment initiated example

{
  "event_type": "payment_initiated",
  "transaction_id": "merchant-order-a8Q3x",
  "status": "INITIATED",
  "payer": {
    "name": "John Doe",
    "mobile_number": "+1XXXXXXXXXX",
    "amount": 25,
    "currency": "TTD"
  },
  "timestamp": "2026-08-01T14:00:00Z",
  "description": "Payment links issued to a Payer[x]"
}

Payment completed example

{
  "event_type": "payment_completed",
  "transaction_id": "merchant-order-w9J2m",
  "status": "PAID",
  "payer": {
    "mobile_number": "+1XXXXXXXXXX",
    "amount": 25,
    "payment_method": "wallet",
    "currency": "TTD"
  },
  "timestamp": "2026-08-01T14:05:30Z",
  "description": "Payer[x] has paid"
}

How to use notify events safely

Treat notify as informational event delivery
Make your receiver idempotent
Do not finalize ledger state from notify alone
Reconcile against GET /payments/status when state matters

Notify is useful for:

driving UI progress
triggering merchant-side workflow steps
recording milestones in your audit trail

Notify is not the best source for:

reconstructing full fee breakdowns
final payer/payee arrays
authoritative request-level terminal state

Notify vs callback vs status

Notify: event-oriented, lightweight
Callback: request snapshot, richer payload
Status lookup: current normalized state from PayWise

Recommended approach:

receive notify events for workflow responsiveness
receive callbacks for request-level state snapshots
poll GET /payments/status for reconciliation, support, and final confirmation

What a notify event represents​

Event envelope​

Payment initiated example​

Payment completed example​

How to use notify events safely​

Notify vs callback vs status​

Related docs​