Bill payment lifecycle

Bill payment execution is asynchronous and state-driven.


State diagram

[STARTING]
    |
    v
[ACTIVE] ──────────────────────────> [COMPLETED]
    |
    | (failure / provider rejection)
    v
[CANCELLED]

All bill payment synthetics pass through ACTIVE before reaching a terminal state.

Full synthetic status set: STARTING, ACTIVE, WAITING, PAUSED, COMPLETED, CANCELLED


Lifecycle transitions

TransitionMeaning
ACTIVE -> COMPLETEDPayment executed successfully
ACTIVE -> CANCELLEDPayment failed and all funds were returned

Timing expectations

PhaseTypical duration
STARTING to ACTIVESeconds
ACTIVE to COMPLETEDSeconds to ~60s (depends on biller/provider)

Some billers operate on batch windows. If the synthetic remains in ACTIVE longer than expected, monitor via SYSTEM_NOTICE webhooks before taking action.


Funds on CANCELLED

When a synthetic reaches CANCELLED, all funds are automatically returned to the operating balance. No manual action is required. Verify via:

  • GET /v2/stats/balance-activities — look for a credit entry with description: PAYMENT_CANCELLATION

Integration model

  1. Treat webhook as primary signal.
  2. Re-fetch synthetic for final authoritative status.
  3. Close idempotently only on terminal states (COMPLETED, CANCELLED).
  4. Use externalId to recognize your bill payment.
  5. Retrieve confirmationCode from the completed synthetic for receipts.

Did this page help you?