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

# Payment Intents

> Creating, validating, and managing payment intents in Lipafy.

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

```typescript
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:

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