> 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.

# Payment Lifecycle & Reconciliation

> How Lipafy transitions payments through Prepare, Control, Approve, and Reconcile stages.

Every financial operation in Lipafy follows a deterministic 4-stage execution pipeline designed to eliminate unauthorized debits, race conditions, and un-reconciled transactions.

---

```
[01 PREPARE] ──────────▶ [02 CONTROL] ──────────▶ [03 APPROVE] ──────────▶ [04 RECONCILE]
Agent / Operator          Server Policy Engine     Human / Multi-Sig Signer   Network Execution
Creates Intent            Validates Balance, Caps   Reviews Snapshot           Settles & Receipts
```

---

### Stage 1: Preparation (`PREPARE`)

* The agent or user drafts a payment intent via SDK, API, or MCP tool.
* Intent specifies destination, amount in integer cents, currency (`KES`), reference, and idempotency key.
* Initial state: `DRAFT`.

---

### Stage 2: Control Layer Validation (`CONTROL`)

* The Lipafy server runs automated policy validation:
  1. **Identity & Key Scoping:** Verifies the calling agent has authorization to request this rail.
  2. **Double-Entry Balance Check:** Verifies sufficient available funds (excluding active escrow holds).
  3. **Velocity Limits:** Calculates cumulative daily and monthly spend against policy caps.
  4. **Duplicate Risk:** Checks if an identical destination and amount were paid within the duplicate suppression window (e.g. 5 minutes).
* If all automated rules pass and amount is below auto-approval limit, state becomes `APPROVED`.
* If amount exceeds the auto-approval threshold, state becomes `PENDING_APPROVAL`.

---

### Stage 3: Human Approval (`APPROVE`)

* For intents in `PENDING_APPROVAL`:
  * Lipafy generates a cryptographically sealed snapshot of the intent.
  * Designated Approvers or the workspace owner receive dashboard review notifications.
  * Approvers review the immutable parameters and digitally sign off.
  * Upon valid signature, state transitions to `APPROVED`.

---

### Stage 4: Network Execution & Reconciliation (`RECONCILE`)

* Once `APPROVED`, the payment engine dispatches the transaction to the telecom or bank network (Safaricom M-Pesa B2B/B2C, PesaLink).
* Intent transitions to `PROCESSING`, and the debit amount is placed on escrow hold.
* **Final Callback:** Within 1–3 seconds, the network returns an official confirmation code (e.g. `QHK892N1P`).
* Upon verified callback:
  * Intent status transitions to `SUCCEEDED`.
  * Escrow hold converts to permanent ledger debit.
  * Reconciled webhook event `payment_intent.succeeded` is dispatched to registered endpoints.

Retries with the same idempotency key return the original intent. Reusing it for different payment material returns a conflict.