Lifecycle and timing
Understand H2H deadlines, verification timing, terminal states, and webhook delivery.
Display-instruction lifecycle
| Point | Behavior |
|---|---|
| Creation | Returns a next_action and a five-minute expires_at |
| Before expiry | Up to three distinct transaction IDs may be submitted |
| Transaction ID accepted | Verification may continue for up to ten minutes beyond the original expiry |
| Temporary verification issue | OmniPay retries during the verification window |
| Rejected transaction ID | Not retried |
| No transaction ID at expiry | Deposit becomes expired |
| No successful match by the verification deadline | Deposit becomes failed |
A transaction ID must be submitted before expires_at. Any additional
processing time is for a transaction ID that was already accepted; it does not
extend the payer's submission deadline.
Redirect lifecycle
For a redirect action, open the returned URL before expires_at and do not
call the manual verification endpoint. Completion is confirmed automatically.
Poll the signed status endpoint or process webhooks until the deposit reaches a
terminal state.
The deposit may remain pending briefly while final confirmation is obtained.
Continue treating it as pending and do not fulfill the order until the status
is succeeded.
Terminal states
succeeded, failed, expired, cancelled, rejected, and refunded are
terminal. A terminal deposit does not return to pending, even if a late status
update arrives.
| Status | Merchant behavior |
|---|---|
succeeded | Fulfill once, after checking the deposit ID, amount, and merchant ID |
failed | Stop checkout and ask the payer to start a new deposit if needed |
expired | Stop using the previous next_action; create a new deposit if the payer retries |
cancelled or rejected | Stop checkout and present a safe retry option |
refunded | Apply your refund business process |
Webhook ordering and retries
For H2H deposits, deposit.created is delivered before a terminal event for the
same deposit. Webhook delivery is at least once from the receiver's perspective,
and a message may be replayed.
Make every webhook consumer idempotent. Store the verified Svix message ID with a unique constraint and ensure duplicate deliveries do not repeat fulfillment.