IUPBCP 登录、账户与账单 Clean-room 协议包-北京尧图网络

IUPBCP 登录、账户与账单 Clean-room 协议包本目录是一套clean-room、厂商中立vendor-neutral的开发契约用于演示印度 UPI 与 Bharat Connect 风格的登录、账户、账单、充值和售后聚合。它不是 Paytm 私有协议也不是 Paytm 或任何机构的生产 API示例不包含真实端点、真实密钥、真实签名、私有签名算法或任何认证/风控绕过方式。本文中的标识符、凭据和证明都只能指向隔离的本地 Mock。协议包不代表已取得 NPCI、PSP、TPAP、Bharat Connect、合作银行或监管机构的接入资格也不能据此处理真实资金。文件职责文件职责openapi.yaml同步 HTTP API 的路径、operationId、安全方案、请求/响应、错误与 JSON Schema 真源asyncapi.yaml聚合状态事件、事件 envelope、channel 与消费者接口真源state-machines.yaml聚合初态、终态、合法迁移、守卫与父子支付映射examples/requests.http覆盖全部 86 个 operationId 的安全 REST Client 示例及变量传递scripts/validate_contracts.rb跨文件引用、状态、安全字段与示例的静态验证Quick start以下命令只面向本地开发。不同工具对 OpenAPI 3.1、JSON Schema 2020-12 和 AsyncAPI 3.0 的支持不同应在团队里固定工具版本并把生成差异纳入评审。先做仓库内语义校验ruby protocols/paytm-cleanroom/scripts/validate_contracts.rb用支持 OpenAPI 3.1 的 linter 校验openapi.yaml用支持 AsyncAPI 3.0 的 linter 校验asyncapi.yaml。例如可在已固定依赖的项目中执行npx redocly lint protocols/paytm-cleanroom/openapi.yaml npx asyncapi validate protocols/paytm-cleanroom/asyncapi.yaml从 OpenAPI 3.1 生成类型化客户端或服务端接口生成物不要反向覆盖契约openapi-generator-cli generate-iprotocols/paytm-cleanroom/openapi.yaml-gtypescript-fetch-obuild/generated/client openapi-generator-cli generate-iprotocols/paytm-cleanroom/openapi.yaml-gspring-obuild/generated/server从 AsyncAPI 3.0 生成事件消费者骨架再按aggregateVersion规则实现 inboxasyncapi generate fromTemplate protocols/paytm-cleanroom/asyncapi.yamlpinned-template-obuild/generated/events启动由 schema 驱动的本地 Mock并把baseUrl配置为该 Mock 的/v1地址。Mock 必须无真实支付能力绝不能连接真实资金轨、银行、PSP 或账单网络。schema mock 只用于契约测试不可用于资金验证。在 REST Client 中打开examples/requests.http配置文档保留值和本地文件变量按章节执行。不要把示例凭据写入源码、日志或测试快照。内置 validator 使用File.read配合YAML.safe_load(..., aliases: true)已在 Ruby 2.6.10 / Psych 3.1 上验证。CI 仍应同时运行当前受支持的Ruby 版本任何兼容性失败都不得通过跳过 OpenAPI、AsyncAPI 或状态机校验来规避。推荐实现顺序固定公共类型、错误 envelope、请求追踪、Idempotency-Key、ETag/If-Match和鉴权中间件。实现身份、设备登记、标准 OTP、注册与会话随后实现 step-up、换号、恢复和账户关闭。实现客户、consent、KYC、证据上传、银行发现/绑定、VPA 和余额授权。实现账单方目录、runtime schema、账单快照、quote、充值目录与 quote。实现 UPI AuthorizationSession、唯一子 PaymentOrder、父级 Bill/Recharge saga、receipt、退款和争议。最后接入 outbox/inbox、AsyncAPI 消费者、对账、审计、可观测性、灾备和全链路契约测试。每一步都先实现state-machines.yaml的迁移守卫和拒绝路径再开放对应 HTTP 写操作。服务边界、聚合与存储建议按 Identity/Device、Customer/KYC、Account/VPA、Bill/Recharge、UPI Orchestrator、Refund/Dispute、Reconciliation 与 Audit 分界。每个聚合独占自己的状态和版本跨聚合只传不透明 ID、冻结快照或事件不共享可写表。Identity 持有 enrollment、OTPChallenge、Session、step-up、换号和恢复OTP 原文只在验证边界短暂处理。Account 持有 Customer、Consent、KycCase、BankAccountLink 与 VPA银行账号只存结构化掩码显示。Bill/Recharge 持有业务快照、quote、父 saga、履约/结算/退款维度但不能写 UPI 表、创建网络尝试或接触银行授权秘密。UPI Orchestrator 独占 AuthorizationSession 与 PaymentOrder并以(aggregateId, aggregateVersion)发布事件。Evidence 存元数据、内容摘要、扫描状态与受控对象引用普通 bearer 域和 recovery 域必须物理或逻辑隔离不能跨域复用 uploadId。Reconciliation 读取不可变流水、外部确认和 outbox不把超时直接写成失败。存储层建议使用聚合版本的条件更新、事务 outbox、消费者 inbox、不可变业务快照和受限审计索引。不要以手机号、VPA、账号或 recovery ID 作为可枚举主键或 bearer credential。登录、注册与会话 ETag登录顺序是 device enrollment → OTP challenge → 标准 OTP verification → registration 或 session。OTP challenge 响应永不回传验证码登录验证只返回一次性authenticationGrant。注册和既有客户创建会话是互斥分支同一 grant 不得消费两次。SessionBundle.sessionEtag或GET /sessions/current的 ETag 只用于 refresh/撤销当前会话GET /sessions/{sessionId}的 ETag 只用于该命名会话GET /sessions的 collection ETag 只用于 revoke-all。不要混用这三类版本。refresh 仍是公开鉴权交换但必须同时提供原 refresh credential、设备证明、幂等键和当前会话 ETag。凭据轮换后立即使旧值失效日志只记录凭据指纹或安全分类不记录值。账户维护、银行绑定、VPA 与余额客户偏好 PATCH、VPA PATCH、银行绑定 action、KYC action、账户关闭 action、step-up 验证和换号 proof attachment 都要求使用刚读取的 ETag。换号需分别验证旧侧和新侧标准 OTP并逐次采用响应中的新 ETagcooling-off 不是可跳过的客户端计时器。银行流程是银行目录 → 账户发现 POST/GET 轮询 →ACCOUNT_BINDINGAuthorizationSession POST/GET → 使用一次性的authorizationSessionRef创建账户绑定 → 读取掩码账户 → 创建/读取/更新 VPA。发现中的UNKNOWN不是“无账户”。余额流程必须先创建并轮询BALANCE_INQUIRYAuthorizationSession再 POST balance inquiry并用GET /upi/balance-inquiries/{balanceInquiryId}轮询。只有SUCCEEDED才读取balance余额来源是发行银行的短期视图不是本地账本余额。AuthorizationSession 在ACTION_REQUIRED时只返回启动受批准组件approved component的短期 launch credential。公共 API 绝不接收、记录或转发 UPI PINUPI PIN 只能在经批准的银行/PSP 组件内采集和处理也不能出现在日志、事件、证据或 Mock fixture。账单、充值与唯一子 Payment saga先读取 biller再读取/billers/{billerId}/parameter-schema。Biller 参数完全由返回的runtime schema运行时 schema驱动customerRef只是示例字段客户端不得为所有 biller 硬编码它也不得提交运行时 schema 未声明的字段。BillFetch 成功后产生不可变、会过期的BillSnapshot。quote 必须绑定该快照与 funding instrumentBillOrder 又必须绑定同一快照和 quote。金额全部是INR minor-unit 十进制字符串例如{amountMinor:100,currency:INR}禁止浮点金额、主单位推断或其他币种。BillOrder 和 RechargeOrder 都先进入PAYMENT_PROVISIONING此时paymentId必须为 null 且不得发起资金网络调用。轮询至AUTH_REQUIRED后父聚合恰好出现一个不可变 childPaymentOrder。客户端按父级nextAction创建/轮询 AuthorizationSession然后 GET child 取得 ETag再以SUBMIT和授权引用修改这个 child。不得创建替代 paymentId父服务只消费 child 状态事件。充值同样执行 operator → plan → subscriber validation → quote → order → provisioning poll → authorization → child GET/SUBMIT→ order/receipt poll。subscriber validation 返回的是短期不透明 token不应长期存储原始订户标识。Receipt 是账单/充值聚合的投影不是银行对账单也不证明尚未完成的 fulfilment 或 settlement 已成功。展示层必须同时显示 payment、fulfilment、settlement 和 refund 状态。证据、退款、争议与恢复普通 KYC/争议证据链是 create upload →PUT .../content→ completion → 各自 GET 轮询到 READY → attachrecovery 域也必须在 completion 后用同一 recovery request 下的专用 GET 轮询到 READY 才能 submit。普通 create body 必须显式携带target: ResourceRefKYC 使用KYC_CASE与后续路径中的同一kycCaseId争议使用DISPUTE与后续路径中的同一disputeId。创建时冻结 purpose、target、media type、字节数、主体、租户、凭据域与 creator context消费证据时服务端以存储的冻结绑定校验 READY、purpose、target 与调用上下文不能信任客户端重报。PUT 的Content-Digest和 completion 的contentDigest必须完全相同。退款是独立聚合以原始业务资源、业务幂等引用、INR 金额和原因创建随后轮询 Refund。争议是独立 casecreate → GET → 普通域证据上传/扫描 → evidence attach → 可选 escalation。退款成功不能重写原 PaymentOrder 的历史事实。恢复严格 non-enumeration请求是否命中客户都返回统一公开投影。完整顺序是新设备 enroll → recovery request → public GET → recovery challenge → 取得otpChallengeId→ 调用标准 OTP verification 得到verificationId→ attach recovery verification → 交换 recovery grant → restricted recovery session。若要求证据必须使用专用 recovery evidence 域create → PUT content → completion → submit。所有步骤都绑定同一 recovery request、session、主体、租户和 recovery credential audience不能调用普通/evidence-uploads代替。最后仅在状态允许时执行CONFIRM_RESTORE公开 GET、recovery ID 或 challenge ID 本身都不是授权。幂等、并发、精确重放与对账所有写请求都带调用方生成的Idempotency-Key其作用域是 method canonical path。相同键只允许精确重放规范化 body、目标资源、认证主体、媒体类型、文件字节和关键头必须相同服务返回原结果同键不同表示必须冲突。对同一业务意图不要在超时后换新键制造第二个支付。要求If-Match的写操作只能使用紧邻目标资源的最新 ETag412/STATE_CONFLICT后重新 GET、重新评估状态再决定是否重试。绝不能盲目覆盖或把父聚合 ETag 用于 child PaymentOrder。PENDING、UNKNOWN、NEEDS_RECONCILIATION都是对账中的不确定状态不是失败、成功、可安全重付或可安全履约信号。保持同一 operation/child按nextStatusCheckAt或退避策略轮询并把最终判定交给 reconciliation。只有safeToCreateNewOperation:true且业务策略明确允许时才可创建新操作。事件、错误、重试、审计与隐私错误处理、重试、审计、隐私必须作为同一条端到端安全链路设计和验收。事件消费必须幂等inbox 以(event.id, consumer)去重以(aggregateId, aggregateVersion)拒绝旧事件、重复事件和乱序覆盖。父 Bill/Recharge 只接受唯一 child 的版本单调事件outbox 发布和聚合提交同事务。错误处理以error.code/category/retryable/safeToCreateNewOperation/correlationId为准HTTP 状态只作传输分类。仅对retryable:true做带抖动的指数退避不确定资金结果即使网络可重试也不能创建替代业务操作。保留服务端X-Request-Id/Trace-Id以便审计但不要把凭据、OTP、设备证明、手机号、VPA、账号或证据内容放进日志、指标标签和异常消息。审计记录应追加写、最小化、按角色隔离并设置留存/删除策略隐私实现需支持目的限制、数据最小化、访问审批、加密、删除/法定保留冲突处理和可追溯导出。应用日志与审计日志不要共用宽权限存储。测试矩阵维度必测内容契约YAML 解析、本地$ref、86 个 operationId 唯一且示例全覆盖、请求/响应 schema、OpenAPI/AsyncAPI lint安全public/bearer/recoveryAuth 隔离OTP 作用域敏感字段、真实端点、完整账号和凭据泄漏扫描幂等首次写、精确重放、同键异 body/主体/路径/文件、过期上传、并发重复提交并发正确/陈旧/跨资源 ETag换号双侧、KYC、closure、payment、dispute 与 recovery 状态冲突Sagaprovisioning 唯一 child、授权过期、提交前取消、提交中断、父子乱序、无替代支付不确定性PENDING、UNKNOWN、NEEDS_RECONCILIATION、对账恢复、权威失败证据、退款补偿Evidence普通域/recovery 域隔离、摘要/长度/media type 一致、恶意文件、扫描未 READY 禁止 attach事件event.id 去重、aggregateVersion 单调、乱序/重复/缺口、outbox/inbox 崩溃恢复隐私与运行non-enumeration、日志脱敏、权限、限流、审计留存、备份恢复与灾备演练如何查阅 86 个操作openapi.yaml的operationId是稳定索引路径和 method 才是实际调用地址。列出全部 86 个操作ruby-ryaml-eoYAML.safe_load(File.read(protocols/paytm-cleanroom/openapi.yaml), [], [], true); o[paths].each { |p, i| i.each { |m, op| puts #{op[operationId]}\t#{m.upcase}\t#{p} if op.is_a?(Hash) op[operationId] } }在examples/requests.http中搜索# operationId 名称可定位安全请求。一个 operationId 可能出现多次以展示不同状态分支或前序变量覆盖统计按唯一 operationId 计算。生产接入前置条件本协议只给出通用合规提示不构成法律意见也不声称任何主体已获资质。生产前至少需要生产控制面应同时覆盖 HSM、数据保护、风控、审计、灾备且均需形成可验证证据。由合格法务与合规团队确认适用的 RBI/NPCI、支付、KYC/AML、Bharat Connect、消费者保护、争议/退款、数据本地化与数据保护要求与 NPCI、PSP、TPAP、Bharat Connect 参与方及合作银行分别完成适用的准入、合同、认证、联调、沙盒和生产审批建立机构级身份、证书生命周期、密钥托管与轮换、HSM、双人控制、职责分离和紧急吊销完成数据分类、加密、数据保护影响评估、目的限制、保留删除、跨境/本地化评估与主体权利流程上线交易风控、欺诈/账户接管防控、AML/制裁筛查、限额、人工复核、投诉与事件响应通过代码、基础设施、供应链、渗透、移动端、API、审计和监管要求的独立评估验证容量、可用性、对账、不可变审计、监控告警、备份恢复、RTO/RPO、灾备切换与定期演练。上述前置条件必须由真实合作方和适用主管机构确认本地 Mock、代码生成成功或契约测试通过均不能替代资质、法务、认证和生产安全审批。

IUPBCP 登录、账户与账单 Clean-room 协议包

相关推荐

宝塔面板实战指南：从零搭建服务器运维图形化管理平台

机械角色手部装甲设计全流程：从结构解析到数字绘画实战

指数成分与行业轮动用Python构建动态行业配置策略 IG50免费开源股票数据API接口

更多资讯

多模态Agent开发：视觉与浏览器自动化实战指南

FreeRTOS中文手册：API行为契约与底层原理深度解析

AI模型部署中的服务编排与性能优化实践

频率感知技术：AGI核心突破与医疗工业应用

Vue.js云台控制UI设计与工业级交互优化实践

工业相机GigE丢帧排查：网卡、网线与系统调优实战指南

今日更新

学生选课系统DFD图绘制指南：边界划分与分层校验实战

JIRA敏捷落地：Scrum角色权限、Sprint与燃尽图避坑指南

SEMI S8人机工程验收实战：从条款拆解到现场实测的完整指南

本周精选

防幻觉智能体架构：电源硬件设计中的大模型编排与工具化实践

OpenGL面试核心考点：渲染管线、矩阵变换与性能排查全解析

全国计算机二级C语言真题PDF高效刷题指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？