Payment Intents

A Payment Intent is the core immutable unit of financial execution in Lipafy. It represents an explicit, policy-checked proposal to disburse or transfer funds.

📋 Payment Intent Payload Schema

interface CreatePaymentIntentPayload {
  // Saved Beneficiary UUID or inline beneficiary specification
  beneficiary_id?: string
  
  // Payment rail type
  payment_type: 'PAYBILL_PAYMENT' | 'TILL_PAYMENT' | 'B2C_PAYMENT' | 'PESALINK_TRANSFER' | 'TAG_TRANSFER'
  
  // Amount in integer minor units (Kenyan cents)
  // E.g. "300000" represents KES 3,000.00
  amount_minor: string
  
  // ISO-4217 Currency (Kenya Shillings)
  currency: 'KES'
  
  // Required for PayBills (Fibre Account, Water Meter, Student ID)
  account_reference?: string
  
  // Clear audit narrative
  purpose: string
  
  // Optional metadata dictionary for agent session tracking
  metadata?: Record<string, string>
}

🔄 Intent Lifecycle States

[DRAFT / PROPOSED]
       │
       ▼
[VALIDATING POLICIES & BALANCE]
       │
   ┌───┴───────────────────────────┐
   ▼                               ▼
[APPROVED / READY]      [PENDING_APPROVAL (Multi-Sig)]
   │                               │
   │                               ▼ (Human signs snapshot)
   │                       [APPROVED]
   │                               │
   └───────────────┬───────────────┘
                   │
                   ▼
             [PROCESSING (Escrow Held)]
                   │
         ┌─────────┴─────────┐
         ▼                   ▼
    [SUCCEEDED]          [FAILED / CANCELLED]
  (Receipt issued)     (Escrow hold released)

State	Description
`DRAFT`	Created by an operator or junior agent; awaiting policy validation.
`PENDING_APPROVAL`	Exceeds auto-approval spending thresholds; waiting in the review queue for authorized signatories.
`APPROVED`	All policy checks passed and cryptographic signatures gathered; queued for immediate execution.
`PROCESSING`	Submitted to the telecom (M-Pesa) or bank network; funds held in double-entry escrow.
`SUCCEEDED`	Final network confirmation received with verified telecom transaction receipt.
`FAILED`	Declined by telecom/bank rail or policy rejection; escrow hold is automatically unlocked.
`CANCELLED`	Explicitly cancelled by an authorized user before execution.

🔑 Idempotency Guarantees

Always pass a unique Idempotency-Key header with every payment creation request:

Idempotency-Key: invoice-9402-run-01

If network timeouts cause your agent to retry the request, Lipafy returns the existing intent without executing duplicate debits.