Overview

Payment Lifecycle & Reconciliation

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.