API Reference

The ItPay Protocol defines 13 REST endpoints organized into five logical groups: Payment Flows, Service Lifecycle, Security, and Integration.

Capability Index

Payment Flows

#	Capability	Endpoint	HTTP	Purpose	State Machine
1	Request Payment	`/v1/payment-intents`	POST	QR-based payment with human scan	`pending → qr_generated → scanning → authorized → captured → succeeded \| expired \| cancelled`
2	Cumulative Pay	`/v1/cumulative/record` + `/v1/cumulative/summary`	POST + GET	Usage-based post-paid billing	`recording → invoiced → payment_pending → paid \| overdue`
3	One-Time Pay	`/v1/payments/one-time`	POST	Simplified instant payment (deep link)	`pending → completed \| failed`
4	Subscribe Pay	`/v1/subscriptions`	POST	Recurring subscription with auto-renew	`pending → active → past_due → cancelled → expired`
5	Refunds & Revocations	`/v1/refunds`	POST	Full/partial refunds with automatic access revocation	`requested → processing → succeeded \| failed`
6	Void Service	`/v1/voids`	POST	Cancel a payment intent, subscription, or record	`requested → voided \| failed`

Service Lifecycle

#	Capability	Endpoint	HTTP	Purpose
7	Broadcast & Discovery	`/v1/services`	POST / GET	Register ServiceManifest and search services
8	Install	`/v1/installs`	POST	Bind payer to service with spending limits
9	KYC / KYB	`/v1/kyc/verify`	POST	Identity verification for payment limits
10	Deliveries	`/v1/deliveries`	POST	Post-payment encrypted fulfillment

Security

#	Capability	Endpoint	HTTP	Purpose
11	API Key Management	`/v1/api-keys`	POST / GET	Structured multi-key credential management
12	Webhook Encryption	`/v1/webhook-endpoints`	POST	Register E2E-encrypted webhook endpoints
13	Escrow Payments	`/v1/escrows`	POST	Trust-minimized payment with dispute resolution

How the Capabilities Relate

                          ┌─────────────────────┐
                          │  Discover + Install  │
                          │  (7. Broadcast       │
                          │   8. Install         │
                          │   9. KYC/KYB)        │
                          └──────────┬──────────┘
                                     │
          ┌──────────────────────────┼──────────────────────────┐
          ▼                          ▼                          ▼
  ┌──────────────┐         ┌────────────────┐      ┌──────────────────┐
  │ QR Payment  │         │ Usage-Based    │      │  Subscription    │
  │ 1. Request  │         │ 2. Cumulative  │      │ 4. Subscribe     │
  │    Payment  │         │    Pay         │      │    Pay           │
  │ 3. One-Time│         └────────────────┘      └──────────────────┘
  └──────┬──────┘                                                      │
         │                                                             │
         └──────────────────────────┬──────────────────────────────────┘
                                    │
                           ┌────────▼────────┐
                           │  Post-Payment   │
                           │ 5. Refunds      │
                           │ 6. Void         │
                           │ 10. Deliveries  │
                           └────────┬────────┘
                                    │
                           ┌────────▼────────┐
                           │  Security        │
                           │ 11. API Keys    │
                           │ 12. Webhook Enc │
                           │ 13. Escrow      │
                           └─────────────────┘

Flow

Discover & Install — A paying agent finds a service via Broadcast & Discovery or MCP tools/list. For repeated use, the payer installs the service with spending limits and auto-pay preferences.
Choose a payment method — Depending on the service's billing model:
- Request Payment (QR) — Human scans a QR code to authorize payment.
- Cumulative Pay — Usage recorded over a billing period and invoiced at end.
- Subscribe Pay — Recurring fixed-interval payments with optional auto-renew.
- One-Time Pay — Simplified instant payment via deep link.
Post-payment — After a payment completes:
- Refunds & Revocations — Return funds and automatically revoke access.
- Void — Cancel before settlement.
- Deliveries — Deliver encrypted digital goods.
Security — Configure API keys, encrypted webhooks, or escrow for high-value transactions.

Common Patterns

Payment Method Discovery via MCP

Every ServiceManifest maps to one or more MCP tools. See MCP Integration for details.

HTTP 402 (x402) Semantics

Request Payment and One-Time Pay support the HTTP 402 Payment Required pattern. See x402 Semantics.

Webhook Events

Capabilities 1–6 emit webhook events to the service's registered endpoint URL. Event types follow <object>.<transition>, e.g. payment_intent.succeeded.

Next Steps

Start with Payment Flows to understand the core payment lifecycle.
See the Quick Start guide for hands-on integration.
Explore Core Objects for detailed field definitions.

Capability Index​

Payment Flows​

Service Lifecycle​

Security​

How the Capabilities Relate​

Flow​

Common Patterns​

Payment Method Discovery via MCP​

HTTP 402 (x402) Semantics​

Webhook Events​

Next Steps​