Architecture Overview
The ItPay Protocol defines a decoupled architecture where payment intent, QR generation, channel routing, and settlement notification are distinct layers. Each layer exposes a well-defined API boundary, allowing implementers to adopt only the components they need without coupling to any single payment network or deployment topology.
System Architecture
┌─────────────────────────────────────────────────────────────┐
│ CLIENT LAYER │
│ ┌──────────┐ ┌────────────┐ ┌──────────┐ ┌──────────┐ │
│ │Agent SDK │ │MCP Client │ │HTTP/REST │ │ Mobile │ │
│ │(Py/TS/Go)│ │(any MCP │ │(curl, │ │ Apps │ │
│ │ │ │ runtime) │ │ fetch, ..)│ │ │ │
│ └────┬─────┘ └─────┬──────┘ └────┬─────┘ └────┬─────┘ │
└───────┼──────────────┼──────────────┼──────────────┼───────┘
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ API GATEWAY │
│ Authentication · Rate Limiting · Routing │
└──────────────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ CORE SERVICES │
│ │
│ ┌────────────────────┐ ┌────────────────────────────┐ │
│ │ │ │ │ │
│ │ Protocol │ │ Payment │ │
│ │ Service │ │ Service │ │
│ │ │ │ │ │
│ │ Agent discovery │ │ Payment intent lifecycle │ │
│ │ Service manifest │ │ Authorization holds │ │
│ │ KYC / install │ │ QR generation │ │
│ │ Capability auth │ │ Invoice management │ │
│ │ │ │ │ │
│ └────────────────────┘ └────────────────────────────┘ │
│ │
│ ┌────────────────────┐ ┌────────────────────────────┐ │
│ │ │ │ │ │
│ │ Subscription │ │ Channel │ │
│ │ Service │ │ Adapter │ │
│ │ │ │ │ │
│ │ Plan config │ │ Unified interface │ │
│ │ Billing cycles │ │ WeChat / Alipay / PromptPay│ │
│ │ Renew / cancel │ │ QRIS / Bank transfer │ │
│ │ Invoice schedule │ │ Error mapping │ │
│ │ │ │ │ │
│ └────────────────────┘ └────────────────────────────┘ │
└──────────────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ DATA LAYER │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │
│ │ PostgreSQL │ │ Redis │ │ S3 / Obj │ │
│ │ │ │ │ │ Store │ │
│ │ • Accounts │ │ • Session │ │ │ │
│ │ • Txns │ │ cache │ │ • QR images│ │
│ │ • Subs │ │ • Rate limit │ │ • Invoice │ │
│ │ • Manifests │ │ • FX cache │ │ PDFs │ │
│ │ • Invoices │ │ • Pub/sub │ │ • Reports │ │
│ │ • Webhooks │ │ • Job queue │ │ • Audit │ │
│ └──────────────┘ └──────────────┘ └────────────┘ │
└─────────────────────────────────────────────────────────────┘
Service Descriptions
| Service | Responsibility | Key Operations |
|---|---|---|
| API Gateway | Entry point for all external traffic. Handles auth, rate limiting, request validation, TLS termination, and route dispatch. | Authenticate · RateLimit · Route · AuditLog |
| Protocol Service | Core protocol logic: agent discovery, service manifest registration, KYC verification, and capability authorization. This is the minimum required service for any protocol implementer. | DiscoverAgents · RegisterManifest · VerifyKYC · AuthorizeCapability |
| Payment Service | Full lifecycle of payment intents: creation, authorization, capture, cancellation, and refund. Generates QR payloads and settlement instructions per channel. | CreateIntent · Authorize · Capture · Refund · GenerateQR · GenerateInvoice |
| Subscription Service | Recurring billing: plan configuration, billing cycles, scheduled invoice generation, and lifecycle management (subscribe, renew, pause, cancel, expire). | ConfigurePlan · GenerateInvoice · Renew · CancelSubscription |
| Channel Adapter | Pluggable connector layer implementing a unified interface (authorize, capture, refund, query) for each payment network. Handles channel-specific signing, encryption, timeouts, and error mapping. | Authorize · Capture · Refund · Query · MapError |
Deployment Architecture
The protocol supports two deployment modes:
Reference Implementation (Go/Gin monolith) A single binary serving all core services behind an API gateway, backed by PostgreSQL and Redis. Suitable for development, staging, and low-to-medium traffic production. All services share the same process and can be deployed via Docker Compose on a single EC2 instance or equivalent VM.
┌─────────────────────────────────────────────┐
│ Single Host / VM │
│ │
│ nginx / Caddy (TLS termination) │
│ │ │
│ Go/Gin monolith (all services) │
│ │ │
│ ┌────┴────┐ ┌───────┐ ┌───────┐ │
│ │PostgreSQL│ │ Redis │ │ S3 │ │
│ └─────────┘ └───────┘ └───────┘ │
└─────────────────────────────────────────────┘
Distributed Deployment (Kubernetes — future) Individual microservices as separate Deployments with Horizontal Pod Autoscaling. PostgreSQL via CloudNativePG operator for high availability; Redis via Redis Operator. Service mesh (Istio/Linkerd) provides mTLS and observability. Helm charts enable repeatable deployments across environments.
Key Design Properties
- Stateless API layer — All services are horizontally scalable; session state lives in Redis, not in application memory.
- Idempotent payment operations — Every payment and settlement endpoint requires an idempotency key, enabling safe retry without double-charge risk.
- At-least-once webhook delivery — Event notifications are retried with exponential backoff (up to 72 hours) until the recipient acknowledges receipt.
- Pluggable channel adapters — New payment networks are added by implementing the standard adapter interface; no changes to core business logic are required.
Related
- Four-Party Payment Model — Money flow between the four actors
- Two-Layer Design — Open Protocol vs. Paid PaaS separation
- Core Objects — Data models powering these services