Paytm 类登录、账户与账单 Clean-room 开发协议包设计日期2026-07-23上游规范2026-07-23-india-upi-bharat-connect-protocol-design.md交付性质可供开发工具消费的厂商中立协议不是 Paytm 私有生产接口目标把公开资料驱动的 Paytm 合规分析和已经审阅的 IUPBCP 领域规范提炼为一套能直接用于客户端、服务端、Mock、契约测试和事件消费者开发的机器可读协议包。边界协议包覆盖登录设备登记、OTP、注册、会话、刷新、注销、step-up、换号和恢复账户客户资料、设备、KYC、银行账户发现/绑定、VPA、余额查询和关闭账单账单方目录、取单、报价、账单订单、充值、收据、退款、争议和证据支撑契约UPI 银行授权、账单子支付查询/提交、幂等、错误、事件和状态机。协议包不包含Paytm 未公开的域名、路径、请求签名、密钥、设备指纹算法或风控阈值OTP、UPI PIN、会话令牌或银行凭据的获取、绕过或重放方法NPCI、PSP、NBBL、COU/BOU 或账单方的私有网络报文对机构接入 UPI 或 Bharat Connect 资格的任何保证。方案选择采用契约优先的 clean-room 方案openapi.yaml是同步消费者 API 的结构真源asyncapi.yaml是跨服务状态事件的结构真源state-machines.yaml定义聚合状态与合法迁移examples/requests.http提供不含真实凭据的端到端调用顺序README.md解释生成、Mock、验证、适配和安全边界。不采用“抓包字段复刻”因为其版本、授权和真实性无法证明也不直接绑定某一 SDK 技术栈避免把协议与实现框架耦合。架构Android / Web Client │ OpenAPI ▼ API Gateway / BFF ├─ Identity Device ├─ Account VPA ├─ Bill / Recharge ├─ UPI Orchestrator └─ Refund / Dispute │ AsyncAPI outbox/inbox ▼ Ledger / Reconciliation / Notification / Audit公共 API 使用/v1、JSON、短期 Bearer 会话、设备绑定、幂等键和乐观锁。UPI PIN 永不进入公共 schema。账单订单通过 provisioning saga 获得唯一子 PaymentOrder客户端只把银行授权引用提交给 UPI OrchestratorBill/Recharge 服务只消费子支付状态事件。文件职责文件职责openapi.yaml路径、参数、请求、响应、错误、安全方案和公共 schemaasyncapi.yaml登录、账户、支付、账单、退款和争议状态事件state-machines.yaml聚合状态、终态、合法迁移和守卫examples/requests.http登录、账户发现、取单和支付的安全示例README.md快速开始、代码生成、Mock、实现顺序和合规说明数据与安全规则金额只使用 INR 最小单位十进制字符串公共 ID 不透明且不可枚举所有写操作要求Idempotency-Key状态修改要求If-MatchOTP 只允许出现在专用验证请求禁止进入响应、事件和日志UPI PIN、CVV、完整账号、真实令牌和生产密钥不得出现在任何 schema 或示例PENDING、UNKNOWN和NEEDS_RECONCILIATION均不得被客户端解释为失败或安全重付支付、履约、结算和退款状态分别建模恢复 ID、challenge ID 和下载 ID 不是 bearer credential。兼容性与验证OpenAPI 使用 3.1.0JSON Schema 使用 2020-12 语义AsyncAPI 使用 3.0.0。验收必须包括YAML 可解析所有本地$ref可解析operationId唯一写操作具备幂等约束状态机中的枚举与 OpenAPI schema 一致AsyncAPI 消息 payload 可解析且不含敏感字段示例不含真实手机号、账号、令牌或 Paytm 私有地址OpenAPI 不出现upiPin、cvv、客户端可声明的initiatorSYSTEM。完成标准开发者可以直接从openapi.yaml生成类型、客户端或服务端接口用 OpenAPI Mock 工具启动无资金能力的沙盒按requests.http跑通登录、账户和账单示例用asyncapi.yaml生成事件消费者骨架用state-machines.yaml编写属性测试并拒绝非法迁移。