Payment statuses

This guide explains the states a payment goes through on SOAMTAR.

Payment lifecycle

               (no PIN entered in time)
                  ┌──────────► failed
                  │
initiated ──► pending ──► success ──► partially_refunded ──► refunded
                  │           │
                  │           └──► disputed ──► success / refunded
                  ├──────────► cancelled
                  └──────────► expired

Simplified lifecycle

The diagram shows the path of a payment from the moment the customer taps "Pay" until the money is received.

What each status means

Status	Meaning
initiated	Created on SOAMTAR, not yet sent to Orange Money (hosted checkout).
pending	Waiting: the payment request was sent to the customer's phone; they have not confirmed it with their PIN yet.
processing	An action from the payer is still expected.
success	Success: Orange Money Sierra Leone confirmed the payment. You can deliver.
failed	Failure: the payment was refused (insufficient balance, wrong PIN, request not confirmed in time, technical error…).
cancelled	Cancelled: the customer cancelled the request or closed the page.
expired	Expired: the payment was not completed within the payment window (2 hours by default).
partially_refunded	Part of a success payment was refunded; more partial refunds are possible.
refunded	The refunds now total the payment amount.

The Orange Money prompt itself gives the customer about 5 minutes to enter their PIN; after that Orange Money reports the request as failed.

Refund statuses

A refund (POST /v1/refunds) has its own status, separate from the payment's:

Status	Meaning
pending	Created, not yet submitted to Orange Money.
processing	Submitted: the credit to the payer's Orange Money wallet is awaiting confirmation.
success	The payer was credited. You receive refund.success, plus payment.refunded or payment.partially_refunded.
failed	The credit was refused (see failure_reason); the amount stays in your balance. You receive refund.failed.

See Refunds.

Golden rules

• A success is final: a success payment never goes back.
• The webhook is the source of truth: never deliver based on what the browser says. Always wait for the confirmation (IPN) sent to your server.
• Full audit: every status change is recorded and visible in your dashboard.

Invariants

• Terminal statuses never move back: a success cannot become pending again. Forbidden transitions are rejected by the database.
• Immutable audit: every status change writes a row in an append-only history.
• Soft delete only: records are retained as required by the applicable regulations.