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

1 interface CreatePaymentIntentPayload {
2   // Saved Beneficiary UUID or inline beneficiary specification
3   beneficiary_id?: string
4   
5   // Payment rail type
6   payment_type: 'PAYBILL_PAYMENT' | 'TILL_PAYMENT' | 'B2C_PAYMENT' | 'PESALINK_TRANSFER' | 'TAG_TRANSFER'
7   
8   // Amount in integer minor units (Kenyan cents)
9   // E.g. "300000" represents KES 3,000.00
10   amount_minor: string
11   
12   // ISO-4217 Currency (Kenya Shillings)
13   currency: 'KES'
14   
15   // Required for PayBills (Fibre Account, Water Meter, Student ID)
16   account_reference?: string
17   
18   // Clear audit narrative
19   purpose: string
20   
21   // Optional metadata dictionary for agent session tracking
22   metadata?: Record<string, string>
23 }

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