Payments

Payment Statuses & Transaction Lifecycle

Understand the payment state machine: track transactions across pending, completed, failed, and refunded states and see how orders update automatically.

Payment Lifecycle Overview

Every payment attempt is tracked in the immutable `payments` ledger, progressing through defined operational states.

Verified Payment Statuses

The four operational payment states in BusinessPlus:

1. Pending (`pending`): Payment initiated (e.g. STK prompt sent to phone or card checkout opened). Awaiting customer authorization.
2. Completed (`completed`): Funds successfully verified and confirmed by the payment gateway or staff member. Unlocks automated receipt generation.
3. Failed (`failed`): Payment rejected due to incorrect PIN, cancelled prompt, expired session, or network error. Displays specific gateway error reason.
4. Refunded (`refunded`): Funds returned to customer following order cancellation or product return. Deducted from net revenue calculations.

Impact on Order Payment Status

Completed payments update the linked order's cumulative `amount_paid`. If `amount_paid >= total`, the order is marked `paid`; if partial, it updates to `partially_paid`.