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

# Autonomous Payments & Scheduled Workflows

> How to configure autonomous execution within strict spending thresholds, automated cron schedules, and agent limits.

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

```typescript
// Recurring cron schedule (e.g. 1st of every month at 08:00 AM)
import { Lipafy } from '@lipafy/sdk'

const lipafy = new Lipafy({ apiKey: process.env.LIPAFY_API_KEY! })

async function runMonthlyBillAutoPilot() {
  // Settle Safaricom Home Fibre
  await lipafy.payments.create({
    paymentType: 'PAYBILL_PAYMENT',
    paybill: '150501',
    accountReference: '0722123456',
    amountMinor: '300000', // KES 3,000.00
    currency: 'KES',
    purpose: 'Automated Monthly Home Fibre Renewal',
  })

  // Settle Nairobi Water
  await lipafy.payments.create({
    paymentType: 'PAYBILL_PAYMENT',
    paybill: '444400',
    accountReference: 'NW-984021',
    amountMinor: '185000', // KES 1,850.00
    currency: 'KES',
    purpose: 'Automated Monthly Water Bill',
  })
}
```

---

### 2. Autonomous Cloud Treasury Top-Up

```typescript
// Server DevOps monitoring bot refills SMS API float when balance drops below KES 1,000
import { Lipafy } from '@lipafy/sdk'

const lipafy = new Lipafy({ apiKey: process.env.LIPAFY_DEVOPS_API_KEY! })

async function checkAndRefillFloat(currentBalanceKes: number) {
  if (currentBalanceKes < 1000) {
    console.log('Low SMS float detected. Initiating automated top-up...')
    
    const intent = await lipafy.payments.create({
      paymentType: 'PAYBILL_PAYMENT',
      paybill: '522522', // Africa's Talking Float PayBill
      accountReference: 'AT-CORP-940',
      amountMinor: '1000000', // KES 10,000.00
      currency: 'KES',
      purpose: 'DevOps Float Auto-Refill (Low Balance Trigger)',
    })
    
    console.log(`Auto-refill completed. Ref: ${intent.network_receipt}`)
  }
}
```

---

### 3. Single-Turn Remote MCP Tool Invocation

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

```json
{
  "name": "lipafy_paybill",
  "arguments": {
    "paybill": "150501",
    "account_number": "0722123456",
    "amount": "3000",
    "purpose": "Monthly Fibre Internet Renewal"
  }
}
```

**Autonomous Success Response**:

```json
{
  "status": "SUCCEEDED",
  "autonomous_execution": true,
  "amount_kes": "3,000.00",
  "fee_kes": "0.00",
  "total_debit_kes": "3,000.00",
  "network_receipt": "QHK892N1P",
  "tracking_id": "pi_9f83a2bc-d14e-4b92",
  "instructions": "Payment of KES 3,000.00 to Safaricom Home Fibre dispatched autonomously via M-Pesa. Receipt: QHK892N1P."
}
```

**Over-Threshold Escalation Response**:

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