Payments

Autonomous Payments & Scheduled Workflows

Lipafy empowers software agents, recurring cron tasks, and microservices to initiate payments autonomously without requiring human intervention on every single low-value transaction.

⚙️ How Autonomous Execution Works

Agent Request (lipafy_pay / lipafy_paybill)
       │
       ▼
[ Policy Evaluation ] ── (Exceeds Threshold) ──► Marks PENDING_APPROVAL & Alerts Dashboard
       │
       ▼ (Within Auto-Approve Caps)
[ Instant Execution ] ──► Dispatches to M-Pesa / Bank Rail (< 3s) & Returns Receipt
  1. Policy Threshold Matching: You define an auto-approval threshold per API key or policy (e.g. auto_approve_up_to: 350000 = KES 3,500.00).
  2. Deterministic Evaluation: When an agent or scheduled task creates a payment intent:
    • If amount <= threshold, the intent automatically transitions from DRAFT ➔ APPROVED ➔ PROCESSING without human clicks.
    • If amount > threshold, the intent immediately pauses in PENDING_APPROVAL and alerts your team dashboard.
  3. Daily & Monthly Velocity Caps: Autonomous execution is strictly bound by cumulative velocity caps. Even if an agent sends 50 separate KES 100 payments, it will be halted the moment it reaches the daily limit (e.g. KES 5,000/day).

🕒 Autonomous Workflows & Code Examples

1. Monthly Utility Auto-Pilot

1// Recurring cron schedule (e.g. 1st of every month at 08:00 AM)
2import { Lipafy } from '@lipafy/sdk'
3
4const lipafy = new Lipafy({ apiKey: process.env.LIPAFY_API_KEY! })
5
6async function runMonthlyBillAutoPilot() {
7  // Settle Safaricom Home Fibre
8  await lipafy.payments.create({
9    paymentType: 'PAYBILL_PAYMENT',
10    paybill: '150501',
11    accountReference: '0722123456',
12    amountMinor: '300000', // KES 3,000.00
13    currency: 'KES',
14    purpose: 'Automated Monthly Home Fibre Renewal',
15  })
16
17  // Settle Nairobi Water
18  await lipafy.payments.create({
19    paymentType: 'PAYBILL_PAYMENT',
20    paybill: '444400',
21    accountReference: 'NW-984021',
22    amountMinor: '185000', // KES 1,850.00
23    currency: 'KES',
24    purpose: 'Automated Monthly Water Bill',
25  })
26}

2. Autonomous Cloud Treasury Top-Up

1// Server DevOps monitoring bot refills SMS API float when balance drops below KES 1,000
2import { Lipafy } from '@lipafy/sdk'
3
4const lipafy = new Lipafy({ apiKey: process.env.LIPAFY_DEVOPS_API_KEY! })
5
6async function checkAndRefillFloat(currentBalanceKes: number) {
7  if (currentBalanceKes < 1000) {
8    console.log('Low SMS float detected. Initiating automated top-up...')
9    
10    const intent = await lipafy.payments.create({
11      paymentType: 'PAYBILL_PAYMENT',
12      paybill: '522522', // Africa's Talking Float PayBill
13      accountReference: 'AT-CORP-940',
14      amountMinor: '1000000', // KES 10,000.00
15      currency: 'KES',
16      purpose: 'DevOps Float Auto-Refill (Low Balance Trigger)',
17    })
18    
19    console.log(`Auto-refill completed. Ref: ${intent.network_receipt}`)
20  }
21}

3. Single-Turn Remote MCP Tool Invocation

When an autonomous agent connects via remote MCP (https://api.lipafy.xyz/mcp), it calls lipafy_paybill:

1{
2  "name": "lipafy_paybill",
3  "arguments": {
4    "paybill": "150501",
5    "account_number": "0722123456",
6    "amount": "3000",
7    "purpose": "Monthly Fibre Internet Renewal"
8  }
9}

Autonomous Success Response:

1{
2  "status": "SUCCEEDED",
3  "autonomous_execution": true,
4  "amount_kes": "3,000.00",
5  "fee_kes": "0.00",
6  "total_debit_kes": "3,000.00",
7  "network_receipt": "QHK892N1P",
8  "tracking_id": "pi_9f83a2bc-d14e-4b92",
9  "instructions": "Payment of KES 3,000.00 to Safaricom Home Fibre dispatched autonomously via M-Pesa. Receipt: QHK892N1P."
10}

Over-Threshold Escalation Response:

1{
2  "status": "APPROVAL_REQUIRED",
3  "autonomous_execution": false,
4  "message": "Payment of KES 5,000.00 exceeds autonomous approval threshold. A human approval request has been created.",
5  "approval_url": "https://app.lipafy.xyz/approvals"
6}