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
| Transition | Meaning |
|---|---|
ACTIVE -> COMPLETED | Payment executed successfully |
ACTIVE -> CANCELLED | Payment failed and all funds were returned |
Timing expectations
| Phase | Typical duration |
|---|---|
STARTING to ACTIVE | Seconds |
ACTIVE to COMPLETED | Seconds 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 withdescription: PAYMENT_CANCELLATION
Integration model
- Treat webhook as primary signal.
- Re-fetch synthetic for final authoritative status.
- Close idempotently only on terminal states (
COMPLETED,CANCELLED). - Use externalId to recognize your bill payment.
- Retrieve
confirmationCodefrom the completed synthetic for receipts.
Updated 7 months ago
Did this page help you?