Broadcast & Discovery
The Broadcast & Discovery capability lets services register their payment manifest and lets paying agents discover available services. It is the first step in any ItPay integration — without a published ServiceManifest, no agent can find or pay your service.
Swimlane: Broadcast & Discovery Lifecycle
The following swimlane diagram shows the full lifecycle — a Seller Agent registers a service, a Buyer Agent discovers it via both search and MCP tools/list, and the manifest transitions through its statuses.
┌──────────────────┐ ┌──────────────┐ ┌──────────────────┐ ┌──────────────┐
│ Seller Agent │ │ ItPay │ │ Buyer Agent │ │ MCP │
│ (Service Owner) │ │ Protocol │ │ (Discoverer) │ │ Server │
└───────┬──────────┘ └──────┬───────┘ └───────┬──────────┘ └──────┬───────┘
│ │ │ │
│ 1. Build │ │ │
│ ServiceManifest │ │ │
│◄───── (name, pricing, │ │ │
│ channels, │ │ │
│ tags...) │ │ │
│ │ │ │
│ 2. POST /v1/services │ │ │
│──────────────────────►│ │ │
│ │ │ │
│ │ 3. Validate │ │
│ │ - Required fields │ │
│ │ - Channel support │ │
│ │ - Pricing format │ │
│ │ - URL format │ │
│ │ - Dedup check │ │
│ │ │ │ │
│ │ ┌────┴────┐ │ │
│ │ │ Invalid │ │ │
│ │ │ Fields? │ │ │
│ │ └────┬────┘ │ │
│ │ ├──┴─── │ │
│ │ yes │ │ no │ │
│ │ │ ▼ │ │
│ │ │ 4. Store │ │
│ │ │ Manifest │ │
│ │ │ status=draft│ │
│ │ │ │ │ │
│ 5a. 422 Validation │ │ │ │ │
│ Error │ │ │ │ │
│◄──────────────────────│ │ │ │ │
│ │ │ │ │ │
│ │ │ ▼ │ │
│ │ │ 6. Return │ │
│ 5b. 201 Created │ │ 201 │ │
│ (status=draft) │ │ + id │ │
│◄──────────────────────│ │ │ │ │
│ │ │ │ │ │
│ 7. Activate Service │ │ │ │ │
│ PATCH /v1/services│ │ │ │ │
│ /:id/activate │ │ │ │ │
│──────────────────────►│ │ │ │ │
│ │ │ │ │ │
│ │ 8. status=active │ │
│ │ Index for search │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ 9. Notify MCP │ │
│ │ Server │ │
│ │────────────────────────────────────────────►│
│ │ │ │
│ │ │ 10. GET /v1/services│
│ │ │ ?q=summarization │
│ │ │ &channel=alipay │
│ │ │────────────────────►│
│ │ │ │
│ │ 11. Search Index │ │
│ │ Filter: active │ │
│ │ Match: name, │ │
│ │ desc, tags │ │
│ │◄──────────────────────│ │
│ │ │ │
│ │ 12. 200 OK │ │
│ │ [manifest...] │ │
│ │──────────────────────►│ │
│ │ │ │
│ │ │ 13. MCP tools/list │
│ │ │────────────────────►│
│ │ │ │
│ │ │ 14. Return tools │
│ │ │ - pay_one_time │
│ │ │ - pay_subscribe │
│ │◄──────────────────────│ │
│ │ │ │
│ 15. Pause Service │ │ │
│ PATCH /v1/services│ │ │
│ /:id/pause │ │ │
│──────────────────────►│ │ │
│ │ 16. status=paused │ │
│ │ Remove from index│ │
│ │ Notify MCP │ │
│ │────────────────────────────────────────────►│
│ │ │ │
│ 17. 200 OK (paused) │ │ │
│◄──────────────────────│ │ │
│ │ │ │
│ 18. Deprecate │ │ │
│──────────────────────►│ │ │
│ │ 19. status=deprecated│ │
│ │ Still visible, │ │
│ │ labelled stale │ │
│◄──────────────────────│ │ │
│ │ │ │
│ 20. Delete (grace) │ │ │
│──────────────────────►│ │ │
│ │ 21. status=deleted │ │
│ │ Purged after TTL │ │
│◄──────────────────────│ │ │
│ │ │ │
Swimlane Legend
| Step | Actor | Action | Description |
|---|---|---|---|
| 1 | Seller Agent | Build manifest | Compose full ServiceManifest with name, description, payment_methods, pricing, accepted_channels, qr_mode, settlement_currency, endpoint, tags |
| 2 | Seller Agent → Protocol | POST /v1/services | Register the manifest |
| 3 | ItPay Protocol | Validate | Check required fields, channel support, pricing format, URL format, dedup |
| 4 | ItPay Protocol | Store | Create manifest record with status: "draft" |
| 5a | Protocol → Seller Agent | 422 Error | Return validation error if fields are invalid |
| 5b | Protocol → Seller Agent | 201 Created | Return the manifest with its generated id |
| 6 | Seller Agent | Activate | PATCH /v1/services/:id/activate transitions draft → active |
| 7 | Protocol | Index | Set status: "active", index for search, notify MCP server |
| 8 | Protocol → MCP Server | Notify | Push manifest into MCP tools/list responses |
| 9 | Buyer Agent → Protocol | GET /v1/services?q=... | Search for services by keyword, channel, payment method |
| 10 | Protocol | Search Index | Full-text match on name/description/tags, filter by status=active |
| 11 | Protocol → Buyer Agent | 200 OK | Return matching manifests with pagination |
| 12 | Buyer Agent → MCP Server | tools/list | Discover available MCP tools |
| 13 | MCP Server | Map manifests | Build tool_name → manifest mapping |
| 14 | MCP Server → Buyer Agent | Return tools | Return tool definitions (e.g. pay_one_time, pay_subscribe) |
| 15 | Seller Agent → Protocol | Pause | PATCH /v1/services/:id/pause |
| 16 | Protocol | Pause + remove | Set status: "paused", remove from search index, notify MCP |
| 17 | Protocol → Seller Agent | 200 OK | Confirm paused |
| 18 | Seller Agent → Protocol | Deprecate | Mark as deprecated (graceful sunset) |
| 19 | Protocol | Deprecate | Set status: "deprecated", still visible with label |
| 20 | Seller Agent → Protocol | Delete | Remove after grace period |
| 21 | Protocol | Delete | Set status: "deleted", purge eventually |
Detailed Interaction Trace
Trace 1: Register a Service (Happy Path)
Human-side dialog (Seller):
"I want to register my AI document summarizer as a pay-per-summary service with Alipay and WeChat support."
Step-by-step trace:
[Seller Agent] [ItPay Protocol] [MCP Server]
│ │ │
│ Build ServiceManifest │ │
│ - name: "Smart Summary" │ │
│ - description: "AI document summary" │ │
│ - payment_methods: one_time=true │ │
│ subscription=true │ │
│ - pricing: one_time=[$0.99] │ │
│ subscription=[Starter $9.99/mo, │ │
│ Pro $29.99/mo] │ │
│ - accepted_channels: [alipay, wechat]│ │
│ - qr_mode: dynamic │ │
│ - settlement_currency: USD │ │
│ - endpoint: https://.../webhook │ │
│ - tags: [summarization, ai, nlp] │ │
│ │ │
│ POST /v1/services │ │
│ Authorization: Bearer <sk_seller> │ │
│──────────────────────────────────────►│ │
│ │ Validate │
│ │ ✓ name present (≤128 chars) │
│ │ ✓ description present │
│ │ ✓ payment_methods has at │
│ │ least one true │
│ │ ✓ pricing matches methods │
│ │ ✓ accepted_channels non-empty │
│ │ ✓ endpoint is valid URL │
│ │ ✓ settlement_currency is ISO │
│ │ ✓ no duplicate name found │
│ │ │
│ │ Store manifest │
│ │ status: "draft" │
│ │ id: "01J7XYKZ1A2B3C4D5E6..." │
│ │ │
│ HTTP 201 Created │ │
│◄──────────────────────────────────────│ │
│ { │ │
│ "id": "01J7XYKZ1A2B3C4D5E6F7G8H9I",│ │
│ "status": "draft", │ │
│ ... │ │
│ } │ │
│ │ │
│ Activate: PATCH /v1/services/ │ │
│ 01J7XYKZ1A2B3C4D5E6F7G8H9I/activate│ │
│──────────────────────────────────────►│ │
│ │ Set status: "active" │
│ │ Index for search │
│ │ │
│ │ Notify MCP server │
│ │───────────────────────────────►│
│ │ │ Register tools
│ │ │ - Smart_Summary__pay_one_time
│ │ │ - Smart_Summary__pay_subscribe
│ HTTP 200 OK │ │
│◄──────────────────────────────────────│ │
│ { "status": "active" } │ │
Trace 2: Discover Services (Buyer Perspective)
Human-side dialog (Buyer):
"Find me an AI summarization service that supports one-time Alipay payments."
[Buyer Agent] [ItPay Protocol] [MCP Server]
│ │ │
│ GET /v1/services │ │
│ ?q=summarization │ │
│ &channel=alipay │ │
│ &payment_method=one_time │ │
│ &limit=5 │ │
│ Authorization: Bearer <sk_buyer> │ │
│──────────────────────────────────────►│ │
│ │ Parse query params │
│ │ q → full-text search │
│ │ channel → filter by channel │
│ │ payment_method → filter by │
│ │ payment_methods.one_time │
│ │ status → default "active" │
│ │ │
│ │ Execute search: │
│ │ SELECT * FROM services │
│ │ WHERE status = 'active' │
│ │ AND (name ILIKE '%sum%' │
│ │ OR tags @> ARRAY['sum']) │
│ │ AND accepted_channels │
│ │ @> ARRAY['alipay'] │
│ │ AND payment_methods->> │
│ │ 'one_time' = 'true' │
│ │ LIMIT 5 OFFSET 0 │
│ │ │
│ HTTP 200 OK │ │
│◄──────────────────────────────────────│ │
│ { │ │
│ "data": [{ │ │
│ "id": "01J7XYKZ1A2B3C4D5E6...", │ │
│ "name": "Smart Summary", │ │
│ "status": "active", │ │
│ "payment_methods": { │ │
│ "one_time": true, │ │
│ "subscription": true │ │
│ }, │ │
│ "pricing": { │ │
│ "one_time": [{"amount":99, │ │
│ "currency":"USD"}] │ │
│ }, │ │
│ "accepted_channels": │ │
│ ["alipay","wechat"] │ │
│ }], │ │
│ "pagination": { │ │
│ "total": 1, "limit": 5, │ │
│ "offset": 0 │ │
│ } │ │
│ } │ │
Trace 3: MCP tools/list Discovery
Human-side dialog (Buyer Agent):
"List all payment tools available through MCP."
[Buyer Agent] [ItPay Protocol] [MCP Server]
│ │ │
│ JSON-RPC: tools/list │ │
│───────────────────────────────────────────────────────────────────────►│
│ │ │
│ │ │ Build tool list from
│ │ │ all active manifests:
│ │ │ - Smart Summary:
│ │ │ tool_name="01J7XYK...__pay_one_time"
│ │ │ desc="Pay one-time for Smart Summary"
│ │ │ params={manifest_id, amount}
│ │ │ - Smart Summary:
│ │ │ tool_name="01J7XYK...__pay_subscribe"
│ │ │ desc="Subscribe to Smart Summary"
│ │ │ params={manifest_id, plan_id}
│ │ │
│ JSON-RPC Response: │ │
│◄────────────────────────────────────────────────────────────────────────│
│ { │ │
│ "tools": [{ │ │
│ "name": "01J7XYKZ1... │ │
│ __pay_one_time", │ │
│ "description": "Pay one-time │ │
│ for Smart Summary — AI-powered │ │
│ document summarization...", │ │
│ "input_schema": { │ │
│ "type": "object", │ │
│ "properties": { │ │
│ "manifest_id": {"type": │ │
│ "string"}, │ │
│ "amount": {"type": │ │
│ "number"} │ │
│ }, │ │
│ "required": ["manifest_id"] │ │
│ } │ │
│ }] │ │
│ } │ │
Trace 4: Error — Validation Failure on Registration
Human-side dialog (Seller):
"I want to register my service, but I'm not sure about the required fields."
[Seller Agent] [ItPay Protocol]
│ │
│ POST /v1/services │
│ { │
│ "name": "My Service", │
│ "description": "A great service", │
│ "payment_methods": { │
│ "one_time": true, │
│ "cumulative": false, │
│ "subscription": false │
│ }, │
│ "pricing": { │
│ "one_time": [{"amount": 100, │
│ "currency": "USD"}] │
│ }, │
│ "accepted_channels": ["alipay"], │
│ "qr_mode": "dynamic", │
│ "settlement_currency": "USD" │
│ } ← MISSING endpoint field! │
│──────────────────────────────────────►│
│ │ Validate
│ │ ✗ endpoint is required
│ │
│ HTTP 422 Unprocessable Entity │
│◄──────────────────────────────────────│
│ { │
│ "error": "validation_error", │
│ "code": "MISSING_REQUIRED_FIELD", │
│ "field": "endpoint", │
│ "message": "The field 'endpoint' │
│ is required for service │
│ registration." │
│ } │
│ │
│ ✗ Install blocked — fix fields, │
│ retry │
Error Handling Per Step
| Step | Error Condition | HTTP Status | Error Code | Recovery |
|---|---|---|---|---|
| 2 (POST) | Missing required field | 422 | MISSING_REQUIRED_FIELD | Add the missing field and retry |
| 2 (POST) | Invalid pricing format | 422 | INVALID_PRICING | Fix pricing structure per schema |
| 2 (POST) | Unsupported channel | 422 | UNSUPPORTED_CHANNEL | Use only supported channel names |
| 2 (POST) | Invalid endpoint URL | 422 | INVALID_URL | Provide valid HTTPS URL |
| 2 (POST) | Duplicate name (active) | 409 | DUPLICATE_NAME | Use a unique name or update existing manifest |
| 2 (POST) | Auth token expired | 401 | UNAUTHORIZED | Refresh API key / re-authenticate |
| 10 (GET) | Invalid query param | 400 | INVALID_QUERY | Fix query parameter name/value |
| 10 (GET) | Offset beyond results | 200 | — | Returns empty data array with correct total |
| 15 (PATCH) | Invalid transition | 409 | INVALID_TRANSITION | Only allowed transitions: draft→active, active↔paused, active→deprecated, deprecated→deleted |
| 13 (MCP) | No active manifests | 200 | — | Returns empty tools array |
Endpoints
| Action | Method | Endpoint | Description |
|---|---|---|---|
| Broadcast (register) | POST | /v1/services | Register or update a ServiceManifest |
| Discovery (search) | GET | /v1/services?q=... | Search for active services by keyword, channel, or payment method |
Broadcast: POST /v1/services
Register a new service or update an existing one. The request body is a ServiceManifest object.
Request Fields
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Human-readable service name (max 128 chars) |
description | string | yes | Brief description of what the service does |
payment_methods | object | yes | Supported payment methods with boolean flags |
payment_methods.one_time | boolean | no | Supports one-time payments |
payment_methods.cumulative | boolean | no | Supports cumulative (usage-based) billing |
payment_methods.subscription | boolean | no | Supports recurring subscriptions |
pricing | object | yes | Pricing details per payment method |
pricing.one_time | array | no | Array of { amount, currency, label } — supported fixed prices |
pricing.cumulative | object | no | { unit, rate, billing_cycle } for usage billing |
pricing.subscription | array | no | Array of plan objects { plan_id, name, amount, currency, interval, features } |
accepted_channels | string[] | yes | Supported payment channels (e.g. alipay, wechat, promptpay) |
qr_mode | string | yes | "dynamic" or "static" — QR code generation mode |
settlement_currency | string | yes | ISO 4217 currency code for settlement |
endpoint | string (URL) | yes | Webhook endpoint for payment events |
tags | string[] | no | Search tags for discovery |
Request Example
POST /v1/services
Content-Type: application/json
Authorization: Bearer sk_liv_xxxxxxxxxx
{
"name": "Smart Summary",
"description": "AI-powered document summarization — upload any PDF and get concise summaries.",
"payment_methods": {
"one_time": true,
"cumulative": false,
"subscription": true
},
"pricing": {
"one_time": [
{ "amount": 99, "currency": "USD", "label": "per summary" }
],
"subscription": [
{
"plan_id": "plan_starter",
"name": "Starter",
"amount": 999,
"currency": "USD",
"interval": "monthly",
"features": ["50 summaries/mo", "Email support"]
},
{
"plan_id": "plan_pro",
"name": "Pro",
"amount": 2999,
"currency": "USD",
"interval": "monthly",
"features": ["500 summaries/mo", "Priority support", "API access"]
}
]
},
"accepted_channels": ["alipay", "wechat"],
"qr_mode": "dynamic",
"settlement_currency": "USD",
"endpoint": "https://api.summarybot.ai/itpay/v1/webhook",
"tags": ["summarization", "ai", "document", "nlp"]
}
Response Example
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": "01J7XYKZ1A2B3C4D5E6F7G8H9I",
"name": "Smart Summary",
"description": "AI-powered document summarization — upload any PDF and get concise summaries.",
"status": "draft",
"payment_methods": {
"one_time": true,
"cumulative": false,
"subscription": true
},
"pricing": {
"one_time": [
{ "amount": 99, "currency": "USD", "label": "per summary" }
],
"subscription": [
{
"plan_id": "plan_starter",
"name": "Starter",
"amount": 999,
"currency": "USD",
"interval": "monthly",
"features": ["50 summaries/mo", "Email support"]
},
{
"plan_id": "plan_pro",
"name": "Pro",
"amount": 2999,
"currency": "USD",
"interval": "monthly",
"features": ["500 summaries/mo", "Priority support", "API access"]
}
]
},
"accepted_channels": ["alipay", "wechat"],
"qr_mode": "dynamic",
"settlement_currency": "USD",
"endpoint": "https://api.summarybot.ai/itpay/v1/webhook",
"tags": ["summarization", "ai", "document", "nlp"],
"created_at": "2026-05-27T09:00:00Z",
"updated_at": "2026-05-27T09:00:00Z"
}
Discovery: GET /v1/services
Search for active services by keyword, channel, or payment method.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
q | string | no | Full-text search across name, description, and tags |
channel | string | no | Filter by payment channel (e.g. alipay, wechat) |
payment_method | string | no | Filter by method (one_time, cumulative, subscription) |
status | string | no | Filter by manifest status (default: active) |
limit | integer | no | Max results per page (default: 20, max: 100) |
offset | integer | no | Pagination offset (default: 0) |
Request Example
GET /v1/services?q=summarization&channel=alipay&payment_method=one_time&limit=5
Authorization: Bearer sk_liv_xxxxxxxxxx
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"id": "01J7XYKZ1A2B3C4D5E6F7G8H9I",
"name": "Smart Summary",
"description": "AI-powered document summarization — upload any PDF and get concise summaries.",
"status": "active",
"payment_methods": {
"one_time": true,
"cumulative": false,
"subscription": true
},
"pricing": {
"one_time": [
{ "amount": 99, "currency": "USD", "label": "per summary" }
],
"subscription": [
{ "plan_id": "plan_starter", "name": "Starter", "amount": 999, "currency": "USD", "interval": "monthly" },
{ "plan_id": "plan_pro", "name": "Pro", "amount": 2999, "currency": "USD", "interval": "monthly" }
]
},
"accepted_channels": ["alipay", "wechat"],
"tags": ["summarization", "ai", "document", "nlp"]
}
],
"pagination": {
"total": 1,
"limit": 5,
"offset": 0
}
}
MCP tools/list Mapping
Every active ServiceManifest automatically generates MCP tool definitions. The mapping follows this convention:
| Manifest Config | MCP Tool Name | MCP Tool Description |
|---|---|---|
payment_methods.one_time: true | <manifest_id>__pay_one_time | Pay one-time for <name> — <description> |
payment_methods.cumulative: true | <manifest_id>__pay_cumulative | Start or resume cumulative billing for <name> |
payment_methods.subscription: true | <manifest_id>__pay_subscribe | Subscribe to <name> — recurring payments |
The MCP server responds to tools/list with all active manifests mapped to their respective tool definitions. See MCP Integration for full details.
State Machine
┌──────────┐
│ draft │
└────┬─────┘
│ activate
▼
┌──────────┐
│ active │
└────┬─────┘
│ pause / resume
▼
┌──────────┐
│ paused │
└────┬─────┘
│ deprecate
▼
┌─────────────┐
│ deprecated │
└──────┬──────┘
│ delete
▼
┌──────────┐
│ deleted │
└──────────┘
Transitions
| From | To | Trigger |
|---|---|---|
draft | active | Service owner activates the manifest |
active | paused | Service owner pauses (temporarily hidden from discovery) |
paused | active | Service owner resumes |
active | deprecated | Service owner marks as deprecated (still visible, but labelled) |
paused | deprecated | Service owner marks as deprecated from paused |
deprecated | deleted | Service is permanently deleted after grace period |
Key Behaviors
- Idempotency: Broadcasting the same
namewith identical fields is idempotent. Update by re-POSTing with modified fields. - Status transitions: Only
activemanifests appear in search results by default.draftmanifests are only visible to the owning API key. - MCP auto-discovery: When a manifest transitions to
active, it is automatically included in subsequent MCPtools/listresponses. Pausing or deprecating a manifest removes it from discovery. - Search indexing: Full-text search indexes
name,description, andtags. Updates to these fields propagate within seconds.
Next Steps
- Install — Bind a payer to a service with payment preferences
- Request Payment — Create a QR-based payment intent
- MCP Integration — Connect via Model Context Protocol