Nile Pay Docs

Every transaction moves through a defined lifecycle from creation to terminal state. Understanding this flow helps you interpret webhook events and build reliable payment handling.

State Diagram

pending → processing → successful
                   ↘ failed
                   ↘ cancelled

Status Definitions

pending

The transaction has been created in the Nile Pay system but has not yet been sent to the payment provider. This is the initial state for all new transactions.

During this state, you can still modify certain transaction details before it moves forward.

The transaction has been submitted to the payment provider and is awaiting completion. For mobile money payments, this typically means the customer has received a PIN prompt or is completing authentication.

Transactions in processing state may take minutes or hours to complete depending on the payment method and customer action.

successful

The payment provider has confirmed the transaction. Funds have moved (or will move shortly) and the transaction is complete.

This is a terminal state. No further status changes will occur for this transaction.

failed

The payment was rejected by the provider or the customer declined to complete payment. Common reasons include insufficient funds, invalid credentials, or provider-side errors.

Failed transactions may be eligible for retry with corrected details.

cancelled

The transaction was cancelled before completion. Cancellation can occur through explicit user action, merchant cancellation via API, or system cancellation due to timeout.

Transition Triggers

Transition	Trigger
pending → processing	SDK submits transaction to provider
processing → successful	Provider confirms payment
processing → failed	Provider rejects or customer declines
processing → cancelled	Timeout reached, explicit cancellation
pending → cancelled	Explicit cancellation before submission

SDK Event Mapping

The SDK exposes events that correspond to these status changes:

transaction.pending: Transaction created
transaction.processing: Submitted to provider
transaction.success: Payment confirmed
transaction.failed: Payment rejected
transaction.cancelled: Transaction cancelled

Your integration should listen for these events to update application state, notify users, and trigger downstream processes.

Transaction Lifecycle