> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.lipafy.xyz/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.lipafy.xyz/_mcp/server.

# Statuses & Reconciliation

> Understanding payment intent statuses, failure codes, and asynchronous network 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. |