Buyer Agent Flow
How an AI agent (buyer) discovers, installs, and pays for services — with or without human involvement.
The ItPay Protocol defines two interaction modes for buyer agents, determined by how the human user configures their agent at install time:
| Mode | Description | Human Involvement |
|---|---|---|
| Always Authorize | Install once, set auto_pay_limit. Subsequent payments under the limit complete silently. | None (under limit) |
| Ask Each Time | No install needed. Every payment requires the human to scan a QR code with their wallet app. | Every transaction |
Mode 1: Always Authorize (Auto-Pay)
The "always authorize" model is for trusted, low-value, or recurring services. The human installs the service once, sets a spending limit, and the agent can auto-pay future requests without asking.
Flow Diagram
┌──────────┐ ┌──────────────┐ ┌──────────┐
│ Buyer │ │ ItPay │ │ Seller │
│ Agent │ │ Protocol │ │ Service │
└────┬─────┘ └──────┬───────┘ └────┬─────┘
│ │ │
│ ── PHASE 1: INSTALL ─────────────────────────│
│ │ │
│ 1. Discover service │ │
│ GET /v1/services │ │
│─────────────────────▶│ │
│◀─────────────────────│ │
│ (ServiceManifest) │ │
│ │ │
│ 2. Install with │ │
│ auto_pay_limit │ │
│ POST /v1/installs │ │
│─────────────────────▶│ │
│◀─────────────────────│ │
│ install_id: ins_xxx │ │
│ status: active │ │
│ │ │
│ ── PHASE 2: HUMAN AUTHORIZES ───────────────│
│ │ │
│ 3. Request payment │ │
│ POST /v1/payment- │ │
│ intents │ │
│─────────────────────▶│ │
│ │ │
│ Check: $0.50 ≤ │ │
│ auto_pay_limit:$1.00 │ │
│ │ │
│ 4. Auto-pay via │ │
│ pre-authorized │ │
│ channel │ │
│◀─────────────────────│ │
│ status: succeeded │ │
│ │ │
│ 5. Call service │ │
│ with proof │ │
│──────────────────────────────────────────────▶│
│ │ │
│ 6. Service delivered │ │
│◀──────────────────────────────────────────────│
│ │ │
│ ── SUBSEQUENT PAYMENTS ────────────────────│
│ │ │
│ 7. Any future │ │
│ request under │ │
│ limit → auto-pay │ │
│ (steps 3-6 repeat │ │
│ automatically) │ │
│ │ │
┌────┴─────┐ ┌──────┴───────┐ ┌────┴─────┐
│ Buyer │ │ ItPay │ │ Seller │
│ Agent │ │ Protocol │ │ Service │
└──────────┘ └──────────────┘ └──────────┘
Phase 1: Install
The buyer agent discovers a service (via MCP tools/list or GET /v1/services) and the human decides to install it with spending limits.
Discover
GET /v1/services?q=summarization&channel=alipay
→ {
"data": [
{
"id": "01J7XYKZ1A2B3C4D5E6F7G8H9I",
"name": "Smart Summary",
"description": "AI document summarization",
"pricing": {
"one_time": [{ "amount": 99, "currency": "USD", "label": "per summary" }]
},
"accepted_channels": ["alipay", "wechat"]
}
]
}
Install (with auto-pay)
POST /v1/installs
Content-Type: application/json
Authorization: Bearer sk_liv...n{
"service_id": "01J7XYKZ1A2B3C4D5E6F7G8H9I",
"payer": {
"agent_id": "agent_cli_a1b2c3d4",
"human_id": "user_frank"
},
"channel": "alipay",
"auto_pay_limit": {
"value": 100,
"currency": "USD"
},
"spending_limits": {
"daily": { "value": 1000, "currency": "USD" },
"monthly": { "value": 5000, "currency": "USD" }
}
}
| Field | Description |
|---|---|
auto_pay_limit | Max single payment that auto-completes without human interaction |
spending_limits.daily | Rolling 24-hour cap on auto-paid transactions |
spending_limits.monthly | Calendar-month cap on auto-paid transactions |
Phase 2: Auto-Pay Behavior
Once installed, the agent can pay without human involvement as long as the amount is under auto_pay_limit.
┌───────────────────────────────────────────────────────┐
│ Auto-Pay Decision Logic │
│ │
│ 1. Receive 402 or create PaymentIntent │
│ 2. Is amount ≤ auto_pay_limit? │
│ ├─ Yes → Is daily/monthly limit remaining? │
│ │ ├─ Yes → Auto-pay (silent) │
│ │ └─ No → Fall back to QR scan │
│ └─ No → Show QR to human │
└───────────────────────────────────────────────────────┘
When auto-pay succeeds:
POST /v1/payment-intents
{
"service_id": "01J7XYKZ1A2B3C4D5E6F7G8H9I",
"type": "one_time",
"amount": { "currency": "USD", "value": 99 },
"auto_pay": true
}
→ {
"id": "pi_01J7XZ1A2B3C4D5E6F7G8H9IK",
"status": "succeeded", ← No QR needed
"channel": "alipay",
"auto_paid": true,
"settlement": { "value": 99, "currency": "USD", "rate": 1.0 }
}
The agent receives a succeeded PaymentIntent immediately — no QR code, no human interaction. It can then call the service directly with the payment proof.
Install Lifecycle
┌─────────────┐
│ pending │ ← Created, not yet activated
└──────┬──────┘
│ activate
▼
┌─────────────┐
│ active │ ← Auto-pay enabled, limits active
└──────┬──────┘
│
┌────┴────┐
│ │
▼ ▼
┌─────────┐ ┌────────┐
│suspended│ │uninstalled│
│(limit │ │(removed) │
│ breached│ │ │
└─────────┘ └────────┘
| Transition | Trigger | Effect |
|---|---|---|
| pending → active | Human confirms install | Auto-pay enabled |
| active → suspended | Daily/monthly limit exceeded | Payments fall back to QR scan |
| active → uninstalled | Human uninstalls via dashboard or API | No further payments possible |
| suspended → active | Limit window resets (next day/month) | Auto-pay resumes |
Mode 2: Ask Each Time (QR Scan)
The "ask each time" model requires human authorization for every transaction. No install is needed — the human scans a QR code with their wallet app each time they want to pay.
Flow Diagram
┌──────────┐ ┌──────────────┐ ┌──────────┐
│ Buyer │ │ ItPay │ │ Seller │
│ Agent │ │ Protocol │ │ Service │
└────┬─────┘ └──────┬───────┘ └────┬─────┘
│ │ │
│ ── PHASE 1: USER ASKS AGENT ────────────────│
│ │ │
│ User: "Summarize │ │
│ this PDF for me" │ │
│ │ │
│ ── PHASE 2: DISCOVER + PAY ────────────────│
│ │ │
│ 1. Get $0.99 │ │
│ summarize tool │ │
│─────────────────────▶│ │
│◀─────────────────────│ │
│ │ │
│ 2. Create │ │
│ PaymentIntent │ │
│─────────────────────▶│ │
│ │ │
│ Over auto_pay_limit? │ │
│ (or no install) │ │
│ → Generate QR │ │
│◀─────────────────────│ │
│ qr_uri + expires_at │ │
│ │ │
│ 3. Show QR to │ │
│ human user │ │
│ │ │
┌────┴─────┐ ┌──────┴───────┐ ┌────┴─────┐
│ Human │ │ │ │ │
└────┬─────┘ │ │ │ │
│ │ │ │ │
│ 4. Scan QR │ │ │ │
│ with │ │ │ │
│ Alipay │ │ │ │
│ │ │ │ │
│ 5. Confirm │ │ │ │
│ ¥6.99 │ │ │ │
│ payment │ │ │ │
│ │ │ │ │
┌────┴─────┐ ┌──────┴───────┐ ┌────┴─────┐
│ Buyer │ │ ItPay │ │ Seller │
│ Agent │ │ Protocol │ │ Service │
└────┬─────┘ └──────┬───────┘ └────┬─────┘
│ │ │
│ 6. Webhook: payment │ │
│ succeeded │ │
│◀─────────────────────│ │
│ │ │
│ 7. Retry service │ │
│ with proof │ │
│──────────────────────────────────────────────▶│
│ │ │
│ 8. Service delivered │ │
│◀──────────────────────────────────────────────│
│ │ │
┌────┴─────┐ ┌──────┴───────┐ ┌────┴─────┐
│ Buyer │ │ ItPay │ │ Seller │
│ Agent │ │ Protocol │ │ Service │
└──────────┘ └──────────────┘ └──────────┘
End-to-End Conversation
Here's how the interaction looks from the human user's perspective:
User: "Summarize this PDF for me."
Agent: "This service costs $0.99 via Alipay. I'll show you a QR code
to scan to complete the payment."
[QR CODE IMAGE DISPLAYED]
Scan with Alipay → ¥6.99
User: [Scans QR with Alipay, confirms payment on phone]
Agent: "✓ Payment received! Here's your summary:
Title: Q4 Financial Report
Pages: 42 pages summarized in 3 key paragraphs
1. Revenue grew 23% YoY driven by APAC expansion...
..."
Key Differences from Always Authorize
| Aspect | Ask Each Time | Always Authorize |
|---|---|---|
| Install required | No | Yes |
| Human scans QR | Every time | Only above auto_pay_limit |
| Latency | 5-30 seconds (human action) | < 1 second (API only) |
| State persistence | Stateless | Stateful (spending limits tracked) |
| UX friction | High (per-transaction) | Low (silent under limit) |
| Best for | High-value, infrequent, new services | Low-value, frequent, trusted services |
The Install API (Full Reference)
The Install endpoint is the bridge between the two modes. If no install exists, or the install has no auto_pay_limit, the protocol falls back to Ask Each Time (QR scan) automatically.
Create an Install
POST /v1/installs
Content-Type: application/json
Authorization: Bearer sk_liv...n{
"service_id": "01J7XYKZ1A2B3C4D5E6F7G8H9I",
"payer": {
"agent_id": "agent_cli_a1b2c3d4",
"human_id": "user_frank"
},
"channel": "alipay",
"auto_pay_limit": {
"value": 100,
"currency": "USD"
},
"spending_limits": {
"daily": { "value": 1000, "currency": "USD" },
"monthly": { "value": 5000, "currency": "USD" }
},
"webhook_url": "https://my-agent.itpay/webhooks"
}
Install States
| State | Meaning | Auto-Pay? |
|---|---|---|
| No install | Service not installed | No → QR always |
pending | Awaiting human confirmation | No |
active | Active with auto-pay | Yes (under limit) |
suspended | Limit breached, awaiting reset | No |
uninstalled | Removed by human | No |
Multi-Service Aggregation
A single buyer agent can install multiple services, each with its own limits:
┌───────────────────────────────────────┐
│ Buyer Agent │
│ (user_frank) │
├───────────────────────────────────────┤
│ │
│ Installed Services: │
│ │
│ ┌─────────────────────────────────┐ │
│ │ Smart Summary │ │
│ │ Auto-pay: $1.00 max │ │
│ │ Daily spent: $0.99 / $10.00 │ │
│ │ Monthly: $4.95 / $50.00 │ │
│ └─────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────┐ │
│ │ Weather API │ │
│ │ Auto-pay: $0.50 max │ │
│ │ Daily spent: $0.00 / $5.00 │ │
│ │ Monthly: $2.50 / $25.00 │ │
│ └─────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────┐ │
│ │ AI Image Generator │ │
│ │ (No install → QR each time) │ │
│ └─────────────────────────────────┘ │
│ │
└───────────────────────────────────────┘
Decision Flowchart: Auto-Pay or QR?
┌──────────────┐
│ Agent needs │
│ to pay │
└──────┬───────┘
│
┌──────▼───────┐
│ Is service │──No──▶ ┌──────────────────┐
│ installed? │ │ Ask Each Time │
└──────┬───────┘ │ Show QR to human │
│ Yes └──────────────────┘
│
┌──────▼───────┐
│ Is install │──No──▶ ┌──────────────────┐
│ status: │ │ Ask Each Time │
│ active? │ │ Show QR to human │
└──────┬───────┘ └──────────────────┘
│ Yes
│
┌──────▼───────┐
│ Amount ≤ │──No──▶ ┌──────────────────┐
│ auto_pay_ │ │ Ask Each Time │
│ limit? │ │ Show QR to human │
└──────┬───────┘ └──────────────────┘
│ Yes
│
┌──────▼───────┐
│ Daily limit │──No──▶ ┌──────────────────┐
│ remaining? │ │ Ask Each Time │
└──────┬───────┘ └──────────────────┘
│ Yes
│
┌──────▼───────┐
│ Monthly limit│──No──▶ ┌──────────────────┐
│ remaining? │ │ Ask Each Time │
└──────┬───────┘ └──────────────────┘
│ Yes
│
┌──────▼───────┐
│ AUTO-PAY │
│ (silent, │
│ 0 latency) │
└──────────────┘
Webhook Events for Buyer Agents
Buyer agents that install services can receive webhook events about their install and spending status:
| Event | Description | When |
|---|---|---|
install.limit_approaching | Daily/monthly spend approaching 80% of cap | Prevent unexpected suspension |
install.suspended | Spending limit exceeded, auto-pay disabled | Notify human |
install.unsuspended | Limit window reset, auto-pay restored | Log for awareness |
payment_intent.auto_paid | A payment was auto-completed under auto_pay_limit | Log for reconciliation |
Next Steps
- Install — Full API reference for the Install endpoint
- Request Payment — QR payment intent creation
- x402 HTTP 402 Semantics — The 402 protocol flow with auto-pay
- Merchant API — How sellers register and receive payments