Overview

Core Concepts

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