Payment Statuses

Every HellOOpass payment status, what it means, and how payments transition between them.

Placeholder API contract

Path, headers, and fields below are illustrative until the final HellOOpass API contract is published.

Every payment resource carries a status field. This page defines each value and how your integration should handle it.

Statuses

Status	Meaning	Action
`pending`	Created; awaiting customer action on hosted checkout.	Wait — do not fulfill.
`processing`	Customer payment underway; funds being confirmed.	Wait — do not fulfill.
`succeeded`	Payment completed successfully.	Fulfill the order exactly once.
`failed`	Terminal failure, e.g. a declined payment method.	Show a retry option; initialize a new payment.
`cancelled`	Explicitly ended, by you or the customer.	Treat as unpaid.
`expired`	Passed its `expires_at` without completing.	Treat as unpaid; re-initialize if the customer returns.

Transitions

pending → processing — the customer submitted payment on hosted checkout.
processing → succeeded — HellOOpass confirmed the payment.
pending / processing → failed — declined or terminally errored.
pending → cancelled — cancelled through the API or by the customer.
pending → expired — the expiry timestamp elapsed.
Terminal states — succeeded, failed, cancelled, expired — never change again.

Only succeeded is paid

Do not fulfill, grant access, or release funds while a payment is pending or processing — either can still end as failed.

Common scenarios

Scenario	Typical final status	What to do
Customer abandons hosted checkout.	`expired`, or `pending` until expiry	Offer a new payment if the customer returns.
Payment method declined.	`failed`	Show a retry that initializes a new payment.
Webhook beats the return redirect.	`succeeded`	Fulfill once from the webhook; keep the return handler idempotent.

Where status appears

status appears in Retrieve Payment Details and inside webhook deliveries (shape illustrative):

{
  "type": "success",
  "data": {
    "id": "pay_01HZX9K2EXAMPLE",
    "status": "succeeded",
    "amount": 1000,
    "currency": "ETB",
    "reference": "order_1024"
  }
}

Webhooks can arrive more than once and out of order — record the payment id and latest status so a stale event never rolls a completed order backward. See Webhook Payload Structure.