Payment States - RohoPay

State Machine

Every RohoPay transaction follows this lifecycle:

                    ┌─────────┐
     API call →     │ PENDING │
                    └────┬────┘
                         │
            ┌────────────┼────────────┐
            ▼                         ▼
     ┌──────────────┐        ┌──────────────┐
     │  SUCCESSFUL  │        │    FAILED    │
     └──────────────┘        └──────────────┘

Terminal states (successful, failed) are permanent — a transaction never moves back to pending once it resolves.

Status Definitions

Status	Description	Mobile Money	Card
`pending`	Transaction created; awaiting user action	USSD prompt sent	3DS not yet completed
`successful`	Payment confirmed by provider webhook	User approved USSD	3DS passed, card charged
`failed`	Payment definitively rejected or timed out	User rejected USSD, expired	Card declined, 3DS failed

Transaction Type States

Collection (Mobile Money)
Disbursement (Mobile Money)
Card Payment

POST /api/v1/collect
     → status: "pending"     ← returned immediately
          │
     User receives USSD prompt on phone
          │
     ┌────┴────┐
     │  User   │
     │  Action │
     └────┬────┘
     Approve │    Reject / Timeout
             │         │
        "successful"  "failed"

Typical resolution time: 10–90 seconds.

POST /api/v1/disburse
     → status: "pending"
          │
     Provider processes transfer
          │
     ┌────┴────┐
     Funds sent │    Transfer failed
                │         │
           "successful"  "failed"

Typical resolution time: 5–30 seconds.

POST /api/v1/checkout
     → status: "pending"
          │
     User redirected to 3DS page
          │
     ┌────┴──────────┐
     │  User authenticates  │
     └────────┬─────────┘
              │
     ┌────────┴────────┐
     │ Provider charges│
     │ card            │
     └────────┬────────┘
     Approved │    Declined
              │       │
       "successful"  "failed"

Typical resolution time: 30 seconds – 5 minutes (3DS user interaction).

Best Practices

Never fulfill orders on pending status

Only mark an order as paid after receiving a successful status via webhook or confirmed by polling. Never fulfill on the initial pending response.

Handle failed payments gracefully

Show the user a clear error and provide a retry option. Avoid retry loops — generate a new idempotency key for each retry attempt.

Implement a timeout on your side

After 2 minutes of polling with no resolution, treat the transaction as “in progress” and inform the user. The status will eventually resolve — your webhook will fire when it does.

Reconcile with the dashboard

Periodically cross-check your local order states against the RohoPay transaction list. The dashboard’s Reconciliation feature can help identify mismatches.

Order Status vs. Transaction Status

RohoPay distinguishes between:

Transaction status (pending / successful / failed) — the payment layer
Order status (for Digital Products: pending / paid / delivered / failed) — your fulfillment layer

Map them like this:

Transaction	→	Your Order
`pending`		`awaiting_payment`
`successful`		`paid` → trigger fulfillment
`failed`		`payment_failed`

​State Machine

​Status Definitions

​Transaction Type States

​Best Practices

​Order Status vs. Transaction Status

State Machine

Status Definitions

Transaction Type States

Best Practices

Order Status vs. Transaction Status