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

# Core Concepts

> Understand the core building blocks of the Lipafy payment orchestration architecture.

Lipafy is built around six foundational primitives that guarantee safe, verifiable financial operations for both individual developers and enterprise finance teams.

---

### 1. Workspaces & Unified Accounts

A **Workspace** is your single unified account container for balances, funds, spending policies, and connected agents. It natively handles both personal lifestyle workflows (recurring utility auto-pilot, @tag transfers) and enterprise operations (multi-user team governance, vendor registries, bulk payroll, and inbound chat commerce).

---

### 2. Beneficiaries

A **Beneficiary** represents a verified, reusable payment destination.

* Destinations are encrypted at rest with AES-256-GCM and cryptographically fingerprinted to prevent duplicate payout attempts.
* Supported formats: Safaricom M-Pesa Phone Numbers (`2547XXXXXXXX`), PayBill shortcodes (`150501`, `444400`), Buy Goods Till numbers (`565444`), and PesaLink bank accounts.
* **Risk Aging:** Lipafy tracks when destination details were last modified. If an agent or operator changes bank details, approval screens prominently highlight the change to prevent invoice fraud.

---

### 3. Payment Intents

A **Payment Intent** is an immutable proposal to move funds. It encapsulates:

* **Amount Minor:** Exact integer amount in Kenyan cents (e.g. `300000` = KES 3,000.00).
* **Destination & Type:** Specific beneficiary, payment rail (`PAYBILL_PAYMENT`, `TILL_PAYMENT`, `B2C_PAYMENT`, `BANK_TRANSFER`, `TAG_TRANSFER`), and account reference.
* **Idempotency Key:** Client-provided UUID to ensure repeated network requests never trigger duplicate payments.
* **Purpose & Narrative:** Clear audit description logged by the agent or operator.

---

### 4. Spending Policies & Guardrails

A **Spending Policy** defines the hard boundaries within which an API key or connected agent is authorized to act:

* **Per-Request Limit:** Maximum KES allowable in a single transaction (e.g. max KES 3,500 for utility renewals).
* **Daily / Monthly Velocity Caps:** Maximum aggregate spend permitted within rolling time windows.
* **Category Allowlists:** Restricting an agent to specific vendor categories (e.g. `['Utility', 'Telecom']`).
* **Auto-Approval Thresholds:** Transactions below the threshold execute autonomously; transactions exceeding the threshold are held for human sign-off.

---

### 5. Dual-Custody Approval Requests

An **Approval Request** is an immutable cryptographic snapshot created when a proposed intent exceeds policy thresholds:

* Contains the exact destination, fee, purpose, and total debit.
* Requires authorized signatories (e.g. Finance Manager or Workspace Owner) to sign off before funds leave the wallet.
* Any material modification to the intent immediately invalidates prior signatures and resets the approval queue.

---

### 6. Double-Entry Ledger & Reconciled Executions

Lipafy maintains a strict, balance-checked double-entry ledger:

* **Escrow Holds:** When an intent is submitted, funds are immediately placed on hold to guarantee settlement availability.
* **Reconciled Succeeded State:** Funds only permanently debit after the telecom or bank network sends a verified success callback and receipt number (e.g. M-Pesa transaction ID `QHK892N1P`).