Skip to main content

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:

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