Statuses & Reconciliation

In distributed payment networks like M-Pesa and PesaLink, an API response acknowledging receipt of a request is not confirmation that money has moved. Lipafy provides deterministic status tracking from initial proposal to final telecom reconciliation.

📊 Complete Status Reference

Status	Category	Description	Wallet Ledger State
`DRAFT`	Initial	Intent prepared; pending policy engine evaluation.	No funds locked
`PENDING_APPROVAL`	Hold	Exceeds autonomous limits; waiting for human or multi-sig approval.	No funds locked
`APPROVED`	Ready	Policy checks and required approvals completed. Queued for execution.	Available balance committed
`PROCESSING`	In-Flight	Dispatched to Safaricom/PesaLink network. Awaiting telecom callback.	Escrow Hold Active
`SUCCEEDED`	Final	Telecom network confirmed success with verified receipt code.	Permanent Ledger Debit
`FAILED`	Final	Declined by network (e.g. invalid phone, insufficient float, recipient timeout).	Escrow Hold Released
`CANCELLED`	Final	Cancelled by an authorized operator or expired in approval queue.	Escrow Hold Released

⚠️ Common Error Codes & Resolutions

Error Code	HTTP Status	Root Cause	Recommended Action
`INSUFFICIENT_FUNDS`	`402`	Workspace available balance is lower than total debit (amount + fee).	Top up workspace balance via M-Pesa or Bank transfer.
`POLICY_VIOLATION_DAILY_CAP`	`403`	Cumulative 24-hour spend exceeds workspace spending policy.	Wait for rolling window reset or request policy adjustment from Admin.
`BENEFICIARY_NOT_ALLOWLISTED`	`403`	The requested PayBill or phone number is not in the policy allowlist.	Add the shortcode/phone to your approved beneficiary registry.
`IDEMPOTENCY_CONFLICT`	`409`	Reused an idempotency key with different amount or destination details.	Generate a fresh UUID `Idempotency-Key` for distinct payment requests.
`TELECOM_TIMEOUT`	`504`	Safaricom/Bank network took > 30s to return status.	Do not re-debit. Intent remains in `PROCESSING` until background polling resolves.