设计稿,未实现,未经沙箱验收。只作接口走查,不发送真实请求。基线已有能力单独列明,不代表此设计已经落地。
设计来源:支付服务 PR #17 · 提交 7d2ae11e91ecd073944f98473ef41a67cd0f6146
| 组 | 数量 | 编号 |
|---|---|---|
| A 易宝同款 | 6 | A1—A6 |
| B 接收易宝通知 | 2 | B1—B2 |
| C 自有接口 | 5 | C1—C5 |
| D 运维检查 | 2 | D1—D2 |
| E 旧接口 | 2 | E1—E2 |
用途:易宝把支付结果通知我们;我们核对无误并存好以后,才回复易宝收到。
P8另用第7个易宝接口“交易日账单下载”(bill-trade-day-download),由后台定时任务调用,不对收银台开放,不新增第18页。P1b、P8批次暂定;对账只记录差错和告警,不自动改资金状态。
B1 · 对应易宝接口
易宝名称支付结果通知
接口标识trade.pay-result
在线文档编号文档无 API ID
易宝路径 / 事件发送到 notifyUrl;无固定供应商请求地址
谁调谁易宝 → 本服务
基线现状已实现(#12、#14);新设计不等于已验收
开发批次(计划)—(已有,不在新能力批次中改)
和易宝不一样的地方
- 接收易宝事件,不虚构供应商固定请求地址。验签及同事务持久化后才应答。
- 支付结果通知默认只在成功时发送,FAIL / TIME_OUT 须在易宝商户交易服务配置另开;不依赖失败/过期通知,后台查原单兜底。该默认时机说明针对支付通知,不扩大到退款通知。
- payerInfo 整个对象及其 bankId、accountName、bankCardNo、mobilePhoneNo、cardType、userID、buyerLogonId、ypAccountBookNo、appID、channelTrxId、bankPostscript 全部子字段不落日志、不推第二跳;顶层 userId、buyerLogonId、yeepayOpenId、bankCardNo 以及 enterprisePayInfo.enterpriseId 同样删除。channelTrxId 只保留后 4 位,完整值不落、不推。
后续范围(第22节)
各角色应得金额后续采用品牌总部转账、再提现,不用余额分账,另行设计;本轮不新增相关接口或执行资金操作。第一阶段分账字段仍一律拒绝。
待定问题与有条件决定
| 编号 / 问题 | 方案 | 状态与条件 | 影响 |
|---|---|---|---|
| 易宝 付款码 / 聚合码订单是否适用关单接口;同步返回缺 `payAmount` 的可信口径;沙箱白名单与配额;通知重试间隔与次数(Q20);对账文件(Q21);退款期限(Q4) | — | 待易宝确认(产品负责人线下问) | P2—P5、验收 |
| Q11 付款人信息 | 不保留:日志和第二跳只留金额、支付方式、时间、渠道交易号后 4 位等对账字段(第 11.2、13.1 节) | 产品负责人已定 11/11 | P1b(日志脱敏)、P7(推送) |
- 未在设计稿明确的字段、类型、必填性和响应层级保持未定义,不根据示例反推 schema。
- 设计稿未列数字信封完整请求字段和解密后完整业务字段;仅保留明确文字。
逐条来源规则与上下文
路径对照
| 能力 | 易宝官方 | API ID / 文档更新 | 本服务路径(照抄) | 方法 / 请求格式 | 现状(c7d23d3) | 计划 PR | | --- | --- | --- | --- | --- | --- | --- | | 付款码收款 | `POST /rest/v1.0/aggpay/pay` | `348be29b…3bb4` / 2026-08-17 22:28:40 | `/rest/v1.0/aggpay/pay` | POST form | 内核已有,对外是 `/api/v1/payments/auth-code` JSON | P2 | | 本单二维码(聚合码) | `POST /rest/v1.0/aggpay/pay-link` | `b49db74d…14d1` / 2026-01-20 20:15:44 | `/rest/v1.0/aggpay/pay-link` | POST form | 未实现 | P3 | | 查收款订单 | `GET /rest/v1.0/trade/order/query` | `1fe6aa42…74eab` / 2026-03-13 17:27:49 | `/rest/v1.0/trade/order/query` | GET query | 内核已有,对外是 `/api/v1/payments/query` JSON | P2 | | 关闭订单 | `POST /rest/v1.0/trade/order/close` | `618b57b3…c85b` / 2025-03-03 11:46:37 | `/rest/v1.0/trade/order/close` | POST form | 只有内部关单队列,无公共路由 | P5 | | 申请退款 | `POST /rest/v1.0/trade/refund` | `35122e4a…76e8` / 2026-03-10 15:25:28 | `/rest/v1.0/trade/refund` | POST form | 未实现 | P4 | | 查退款 | `GET /rest/v1.0/trade/refund/query` | `ddb05a9b…0b26` / 2026-10-10 16:45:06 | `/rest/v1.0/trade/refund/query` | GET query | 未实现 | P4 | | 支付结果通知 | `trade.pay-result`(发往 notifyUrl) | 文档无 API ID | 本服务接收:`/api/v1/notify/yeepay`(沿用) | 易宝 → 本服务 | 已实现(#12、#14) | — | | 退款结果通知 | `trade.refund-result` | 文档无 API ID | 本服务接收:建议 `/api/v1/notify/yeepay/refund` | 易宝 → 本服务 | 当前回 FAIL/503 保留重试 | P4 | | 第二跳推送 | 无(本服务自有) | — | 调用方登记的地址 | 本服务 → 调用方 | 未实现 | P7 | API ID 全文:付款码 `348be29b03b2430fa8910175524d3bb4`;聚合码 `b49db74dd1fe4099836cf9e7b5d114d1`;查单 `1fe6aa427dc941cc8228fe9700a74eab`;关单 `618b57b3a47d4447bf009e261e73c85b`;退款 `35122e4a4b5b406797243b86083376e8`;查退款 `ddb05a9b714b4edba112c0eab0705b26`。实现时以当天重新拉取的官方文档为准,变化写进 PR。 不使用:旧 `/rest/v1.0/sys/trade/*` 接口族;不用 `/aggpay/pre-pay` 代替付款码或聚合码。
易宝 → 本服务(第一跳)
- 支付通知沿用 `/api/v1/notify/yeepay`:RSA 数字信封解密、对原始明文验签、核对商户 / 订单 / 金额,回执、状态、成功事实、版本和事件同事务提交后才回 HTTP 200 + 纯文本 `SUCCESS`;畸形 / 坏签 400 + `FAIL`;持久化失败 503 + `FAIL`;未知订单只落摘要回执,不创建收款。#14 的失败 / 过期通知金额兼容保留。易宝支付结果通知**默认只在支付成功时发**,订单过期(`TIME_OUT`)和支付失败(`FAIL`)要在易宝商户交易服务配置里另开才会通知(Claude 11/11 按官方 Skill 和在线文档核对);本服务**不依赖失败和过期通知**,没开这个配置时靠后台查原单了结(现有轮询就是这样),#14 的兼容只在开了配置时用到。 - 退款通知(P4):建议新路径 `/api/v1/notify/yeepay/refund`,同样的落库后应答规则;`status` 为 SUCCESS / FAILED / CANCEL;更新退款单和占额。 - 发给易宝的 `notifyUrl` 一律是本服务入口。切换环境、灾备时回调域名保持稳定(部署方案第七节)。
记什么
新表 `payment_exchange_logs`,只追加:
| 字段 | 说明 |
| --- | --- |
| `log_uid` | **记录的稳定标识**:应用在写之前生成的 UUIDv7(时间有序、随机部分保证多节点不重复),数据库和文件写同一个值;数据库唯一索引。数据库写失败时文件里照样有它,两份按它一一对应 |
| `node` | 写这条记录的节点标识(和文件名里的一致) |
| `id`、`created_at` | `id` 是数据库自增主键,只在库内用,**不写进文件、不作为两份之间的关联号**;`created_at` 写入时间(毫秒,应用生成,两份相同) |
| `trace_id` | 一次调用方请求贯穿三段的关联号;后台任务自己生成 |
| `segment` | `caller`(调用方 ↔ 本服务)、`channel`(本服务 ↔ 易宝)、`notify`(易宝 → 本服务)、`push`(本服务 → 调用方,第二跳);**只在文件里**另有 `state`(状态事件行,第 13.3 节) |
| `source` | 只在数据库:`direct`(正常写入)/ `file_backfill`(补写任务从文件补插) |
| `backfilled`、`backfilled_for` | 只在文件:补写任务补进来的行标 `backfilled=true`;替已下线节点补的另标 `backfilled_for=<节点>` |
| `operation` | `aggpay.pay`、`aggpay.pay-link`、`order.query`、`order.close`、`refund`、`refund.query`、`pay-result`、`refund-result` 等 |
| `app_ref`、`brand_ref`、`store_ref` | 调用方和授权范围 |
| `bill_no`、`order_id`、`payment_ref`、`refund_request_id` | 查整条链路用的号码 |
| `http_method`、`path`、`http_status` | |
| `result_code`、`result_status` | 易宝 `code` / `status` 或本服务 `error.code` |
| `outcome` | 本服务判定:`accepted`、`succeeded`、`failed`、`unknown`、`rejected`、`conflict` 等 |
| `latency_ms` | 耗时 |
| `request_body`、`response_body` | 脱敏后的完整请求和返回(JSON 文本) |
| `body_sha256` | 原始字节摘要(脱敏前),用于核对 |
| `related_trace_id` | 回调、后台查单、关单 worker、第二跳生成自己的 `trace_id`,这里填触发它的原请求 `trace_id`(能找到时);找不到的靠 `order_id` / `payment_ref` 串 |
| `auth_result` | 第①段:`ok` / `scope_denied`,以及和 401 `details.reason` 同一套的 `invalid_content_type` / `query_not_allowed` / `missing_auth_header` / `timestamp_out_of_window` / `non_canonical` / `invalid_signature` / `nonce_reused` / `nonce_unavailable`(第 4.3 节) |
| `dispatch_stage` | 第②段:`not_sent`(预算不足等未发出)/ `sent` / `response_received` / `timeout_after_send` |
| `signature_result` | 第②段应答 `x-yop-sign` 验签、第③段通知验签:`ok` / `bad` / `missing` |
| `notification_key` | 第③段:通知去重键(现有 `channel_notifications.notification_key`) |
| `match_result` | 第③段:`matched` / `unknown_order` / `identity_mismatch` / `amount_mismatch` |
| `dedupe_result` | 第③段:`first` / `duplicate` |
| `persist_result` | 第③段:`committed` / `rolled_back` |
| `ack` | 第③段回给易宝的应答:HTTP 状态 + `SUCCESS` / `FAIL` |
部署清单 C1—C3 的逐项对应:C1 调用方→支付 = 第①段(`auth_result`、`request_body`、`response_body`、`app_ref`、`latency_ms`、`trace_id`);C2 支付→易宝 = 第②段(`operation`、`order_id`、`dispatch_stage`、`result_code`、`signature_result`、`latency_ms`、`outcome=unknown` 表示未明);C3 易宝→支付 = 第③段(`notification_key`、`signature_result`、`match_result`、`dedupe_result`、`persist_result`、`ack`、`latency_ms`)。
脱敏样例(合成数据,非真实订单):
```text
segment=caller operation=aggpay.pay trace_id=t-01 order_id=100000000000000123_1 auth_result=ok
request_body={"merchantNo":"<商编>","orderId":"100000000000000123_1","orderAmount":"30.00","authCode":"****1234",...}
response_body={"code":"00000","status":"PROCESSING",...} http_status=200 outcome=unknown latency_ms=4120
segment=channel operation=aggpay.pay trace_id=t-01 dispatch_stage=response_received signature_result=ok result_code=00000 result_status=PROCESSING
segment=channel operation=order.query trace_id=t-07 related_trace_id=t-01 result_code=OPR00000 result_status=SUCCESS signature_result=ok
segment=notify operation=pay-result trace_id=t-09 order_id=100000000000000123_1 notification_key=<摘要> signature_result=ok
match_result=matched dedupe_result=first persist_result=committed ack=200 SUCCESS
```
- “所有请求和返回的数据都要记录”:按上表记完整报文,只做下面的脱敏。鉴权失败的请求也记(不认领 nonce、不进业务),但不记请求体;为防刷请求撑爆表,鉴权失败的写入按来源 IP + `app_ref` 限速(建议每分钟每来源前 60 条全记,之后每分钟只记 1 条汇总并带计数),超过阈值发告警(第 14 节“鉴权失败激增”)。
- 脱敏:`authCode` 只留后四位(日志里写 `****1234`);签名(`X-SP-Signature`、`x-yop-sign`、`Authorization`)、密钥、证书、数字信封密文不记;**付款人信息不落日志**(Q11 已定):付款人标识:顶层的 `userId`、`buyerLogonId`、`yeepayOpenId`、`bankCardNo`,以及 `payerInfo` 整个对象(子字段 `bankId`、`accountName`、`bankCardNo`、`mobilePhoneNo`、`cardType`、`userID`、`buyerLogonId`、`ypAccountBookNo`、`appID`、`channelTrxId`、`bankPostscript`),以及 `enterprisePayInfo.enterpriseId`,在写日志前删除(判断标准同第 3.3 节);`channelTrxId` 只留后 4 位;只留对账需要的金额、支付方式、时间、渠道交易号后 4 位。注意区分:禁止出现在对外返回里的是**付款码**尾号;**渠道交易号后 4 位**(`channel_trade_no_last4`,GPAY02-07)是允许返回的,不要一起删掉。
- 写入时机:第①段在返回前写;第②段在渠道调用返回或超时后写;第③段在应答前写;写日志失败不改变资金判定,但要告警(不能因为日志写不进去就把成功说成失败)。待定问题与决定
11/11 产品负责人定了全部非易宝项。“产品负责人已定”立即生效;“Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效”这几条由 Lihao 在 #17 提异议,有异议就按他的意见改文档后重新复审。只有 Q15 挡 P1,其余到 P2、P4、P7 才用到。
| # | 问题 | 决定 | 状态 | 影响 |
| --- | --- | --- | --- | --- |
| Q1 | 返回业务结果对象还是完整 YOP 网关响应 | 只返回易宝业务结果对象(第 3.3、6.1 节) | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P2 |
| Q2 | 是否加本服务响应签名 | 第一阶段不加(第 6.1 节) | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P2 |
| Q3 | `merchantNo` 是否必填 | 必填(第 3.3 节) | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P2 |
| Q4 | 并行期怎么切、序号位数 | 按门店整体切换;序号 1—6 位、不补零(第 7 节) | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P2 |
| Q5 | `expiredTime` 范围 | 付款码 1—15 分钟、不传补 15 分钟;二维码 1—60 分钟、不传补 5 分钟(第 3.3、3.4 节) | 产品负责人已定 11/11 | P2、P3 |
| Q6 | 二维码 `scene` 默认值 | 不传时补 `{"WECHAT":"OFFLINE","ALIPAY":"OFFLINE"}`(第 3.4 节) | 产品负责人已定 11/11 | P3 |
| Q7 | 二维码换新、隐式关前代 | 去掉 `renew`,POS“关单 → 新 orderId”;不做隐式关前代,未关旧码时 409 拦住(第 3.4、10 节) | 产品负责人已定 11/11;POS 流程部分同 Q1 的异议期 | P3、P5 |
| Q8 | 退款 / 查退款定位方式 | 只按 orderId(第 3.7、3.8 节) | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P4 |
| Q9 | 退款失败、`SUSPEND` | 不开通补充卡信息退款;失败类都标待核、资金类告警、转人工,不自动重退、不自动结束退款(第 3.7 节) | 产品负责人已定 11/10 | P4 |
| Q10 | `biz_no`、`order_kind` | 不进易宝字段,内部按 bill_no 关联(第 7 节) | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P2 |
| Q11 | 付款人信息 | 不保留:日志和第二跳只留金额、支付方式、时间、渠道交易号后 4 位等对账字段(第 11.2、13.1 节) | 产品负责人已定 11/11 | P1b(日志脱敏)、P7(推送) |
| Q12 | 告警接收 | 专门的 Slack 频道;接收人产品负责人、Lihao;资金类 15 分钟内响应,其他当天;webhook 只放 `.env`,P6 前提供(第 14.2 节) | 产品负责人已定 11/11 | P6 |
| Q13 | PR 顺序 | P1→P7(第 17 节);11/11 暂定加 P1b(紧跟 P1)和 P8(P7 之后) | 产品负责人已定 11/11 | 全部 |
| Q14 | 新错误码名字和 HTTP 状态 | 按第 5 节 | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P2 起 |
| Q15 | 签名 v2 逐字节规则 | 按第 4.3 节;`Content-Type` 只认 `application/x-www-form-urlencoded`,不带 charset | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | **P1** |
| Q16 | 第二跳是否推 `payment.unknown` | 第一阶段不推(第 11.2 节) | 产品负责人已定 11/11 | P7 |
| Q17 | 通过标准数值 | 按第 21.3 节 | 产品负责人已定 11/11 | 验收 |
| Q18 | `REFUND_IN_PROGRESS`、`REFUND_AMOUNT_EXCEEDED` | 按第 3.7、5 节 | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P4 |
| Q19 | 第二跳推送签名 v2 | 按第 11.2 节,POS 侧同步实现 | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P7 |
| 报文存储 | 报文怎么存、存多久 | 数据库+文件双写,两份都长期保留,不设清理;文件和库不同盘、每天复制到服务器外(第 13.2、13.3 节) | 产品负责人已定 11/11 | P1b、部署 |
| 报文记录批次 | 报文记录何时做 | 从 P6 提到 P1b,内部只读查询一起提前(第 17 节) | 产品负责人暂定 11/11 | P1b |
| 每日对账 | 上线前是否加对账 | 加 P8 每日对账,收真钱前置;差错只记录告警、不自动改资金状态(第 13.5 节) | 批次暂定;“不自动改状态”已定 11/11 | P8 |
| 判断顺序(11/11 复审) | `Content-Type` 不对回什么 | 统一 401,在验签前判断(第 3.2、4.3 节) | 文档前后统一,属 Q15 范围,异议期同 Q15 | **P1** |
| orderId 序号写法 | 序号能否 0 开头 | 不能,`_01` 回 422(第 3.3、7 节),与 Q4 一致 | 文档前后统一 | P2 |
| 401 原因 | 401 能否分清原因 | `details.reason` 八个取值(含 `nonce_unavailable`)、日志同一套、带 `WWW-Authenticate`;调用方自己生成一次表单字节再签名发送;向量 11 组(第 4.3 节) | Lihao 11/11 要求;名字按他举例,异议期同 Q15 | **P1** |
| 同步返回里的付款人字段 | 付款码、查单的同步返回按 Q1 原样会带上易宝给的付款人字段(`payerInfo` 等),要不要也去掉 | 去掉,清单见第 3.3 节,其余字段照旧(第 1 节第 4 处例外) | 产品负责人已定 11/11 12:49(亚利桑那) | P2 |
| 备份恢复后收款怎么重新开放 | 恢复后当时所有在用收款入口(A1、A2,并行期还有旧付款码接口 E1)何时开放,系统要不要按账单拦 | 先停后开:比对清单交到人手里再开,停的期间收现金;不做按账单拦截,通知门店写进恢复手册(第 13.3 节) | 产品负责人已定 11/11 14:11(亚利桑那) | P1b、部署方案 |
| 旧接口 E1、E2 的付款人信息 | 旧 `/api/v1/payments/auth-code`、`/api/v1/payments/query` 返回里带不带 | 现状:**不带**。两者都返回本服务自己的 `PaymentResource`(基线 `c7d23d3` 的 `app/Http/Resources/PaymentResource.php`),字段是内部单号、金额、状态、`channel_trade_no_last4` 等,不透传易宝返回,没有 `payerInfo`、`userId`、`buyerLogonId` 等。建议:不用改,在并行期回归里加一条“旧接口返回不出现付款人字段” | 现状已核对;建议待产品负责人确认 | P2 回归 |
| 渠道交易号后 4 位放哪 | 查单是否加 | 查单不加;只在 facts 和第二跳推送给(第 3.5、12、17 节) | 文档前后统一 | P7 |
| 商户结构 | 品牌总部、门店、教练等的易宝类型 | 门店是品牌总部下的入驻商户(发起方商编 = 平台商编);按商编可配置(第 7.1 节) | 门店:产品负责人已定 11/11;教练、供应链、商户池中的商户:**待确认** | P2 配置 |
| 易宝 | 付款码 / 聚合码订单是否适用关单接口;同步返回缺 `payAmount` 的可信口径;沙箱白名单与配额;通知重试间隔与次数(Q20);对账文件(Q21);退款期限(Q4) | — | **待易宝确认**(产品负责人线下问) | P2—P5、验收 |易宝官方 Skill 核对结果(11/10 产品负责人建议)
依据:`github.com/Yeepay-Open-Platform/yeepay-skills`,技能 `yeepay-payment-integration` v1.5.0,固定提交 `ccb7783a7e1eab63f77b4f78e470c617499ab440`(和 #16 官方向量是同一提交)。只读 `references/`,没有运行 `scripts/`,没有使用任何密钥。另对照易宝在线文档(11/10 拉取)。
| 待确认点 | Skill / 文档怎么说 | 结论 | 对本设计的影响 |
| --- | --- | --- | --- |
| 付款码、聚合码订单能不能调关单 | Skill 的付款码、聚合码场景只列“下单 + 查单”,没有关单;`api-index.yaml` 里没有关单接口。在线关单文档(`618b57b3…c85b`,2025-03-03)没有提到付款码 / 聚合码,既没说适用也没说不适用,只写了合单子单不支持关单(`OPR00093`) | **仍未确认**,Skill 回答不了 | 第 3.6 节不变:关单结果只当提示,靠查原单定终态;仍须向易宝确认或实测 |
| 通知重试间隔和次数(易宝答复 Q20) | 《结果通知机制说明》:未按约定应答就自动重试,“具体频次因产品/场景略有差异,以控制台发送记录为准”;控制台可查询、手工重发、换地址重发 | **没有固定数字** | 设计不依赖重试频次:落库后才应答、重复通知幂等、主动查单兜底(第 9、11 节)。上线手册加一条:通知异常时到控制台“结果通知”查发送记录、手工重发 |
| 通知成功应答 | RSA:HTTP 200 + 纯文本 `SUCCESS`;SM2:200 + `{"result":"SUCCESS"}` 并签名 | 和现有实现一致 | 无 |
| 回调和查单不一致 | 《结果通知机制说明》:“回调与查单不一致时以查单为准” | 和本设计一致的部分:终态靠查单确认 | 本设计更保守:和**已确认终态**矛盾时不直接改,标待核(GPAY 已定规则 6),不冲突 |
| 退款 `SUSPEND` | 《退款》:只有商户开通了“补充卡信息退款”才会停在 `SUSPEND`,需调 `trade/refund/supply` 补卡或 `trade/refund/end` 结束;**没开通时**,原路退款失败**且能取到支付卡信息**才会自动转打款退款,转打款仍失败(或取不到卡信息)钱退回商户易宝账户 | 第一阶段不开通该服务,正常不会出现 `SUSPEND` | 第 3.7 节:收到 `SUSPEND` 说明商户配置和约定不符,标待核、告警,不自动重退、不自动调 supply / end(Q9 已按此定:不开通该服务) |
| 退款失败后的资金去向 | 同上:没开通补卡退款时,原路失败且转打款没发生或也失败,钱回到商户易宝账户 | 门店直收要有对应账务处理 | 告警由 P4 写入、P6 外发;每日对账(P8)核对退款;退款失败后用**同一个** `refundRequestId` 重试(《退款》易错点) |
| 付款码必传字段 | 《被扫支付》:`terminalId`、`userIp`、`scene=OFFLINE` 必传;`expiredTime` 不传默认 24 小时 | 在线文档:`scene` 条件必填(按渠道,银联除外),`terminalId` 非必填(线下面对面场景请传);Skill 两项都写必传 | 第 3.3 节:微信、支付宝 `scene=OFFLINE` 必填(符合在线文档);`terminalId` 按 Skill 和线下面对面场景收紧为必填 |
| 付款码同步返回 | 《被扫支付》:同步可能是 `SUCCESS` 或处理中,处理中必须轮询查单,不可判失败或重复下单 | 和现有实现一致 | 无 |
| 聚合码的 `payWay`、`userIp` | Skill《主扫支付(聚合码)》写 `payWay=USER_SCAN`、`userIp` 按需;在线 pay-link 文档(2026-01-20)没有这两个字段 | 两份官方材料不一致 | 先按在线文档不传(沿用 PAY-r7 字段核对的处理),沙箱联调时确认;如网关要求再改 |
| 聚合码前置条件 | 开通“用户扫码支付宝线上”“用户扫码微信线上”,完成子商户认证,配置公众号 appid、appSecret、支付授权目录(`/rest/v2.0/aggpay/wechat-config/add`) | 与 PAY-r7 开工前要办一致 | 列入 P3 前置条件,由产品负责人对易宝办 |
| 沙箱能验什么 | 《沙箱环境联调测试》:沙箱“主要支持 YOP 网关校验、商户回调通知”,是模拟环境,“所有返回码及业务逻辑以正式环境为准” | 关单适用性、真实 `payAmount`、真实失败码**沙箱证明不了** | 验收里这几项沙箱结果只算网关和报文验证,渠道能力本身标“待核 / 阻塞”,靠易宝书面答复补证据。正式环境验证**不属于本轮验收**,也不是自动的下一步;要不要做、怎么做由产品负责人另行决定(不做真实扣款、退款的红线不变) |
| 易宝回调来源限制 | 《回调网络配置》:出口 IP 会变,推荐域名白名单(`out.yeepay.com`),只能用 IP 时每小时解析一次同步规则 | — | 部署清单 A3 补充:不要把易宝回调 IP 写死 |
| 同步返回缺 `payAmount` 的口径、YOP 完整响应与签名、沙箱配额 | Skill 未涉及 | 仍未确认 | 维持第 6.2 节和 Q1 |
| 关单返回码(11/11 补充) | 在线关单文档另列 `OPR18010`、`OPR18013`、`OPR18015`、`OPR13003`、`P00013`、`P00016`、`OPR00024`、`OPR00025` | 已逐个定处理 | 第 3.6 节返回码表 |
| 支付通知何时发(11/11 补充) | 默认只在支付成功时发,过期和失败要在商户交易服务配置里另开 | 不依赖失败 / 过期通知 | 第 11.1 节:靠查原单了结 |
| 通知 `payerInfo` 子字段(11/11 补充) | `bankId`、`accountName`、`bankCardNo`、`mobilePhoneNo`、`cardType`、`userID`、`buyerLogonId`、`ypAccountBookNo`、`appID`、`channelTrxId`、`bankPostscript` | 全部不落日志、不推;`channelTrxId` 只留后 4 位 | 第 11.2、13.1 节 |
| 聚合码 `expiredTime` 默认(11/11 补充) | 不传时易宝默认 1 小时(付款码 24 小时) | 本服务补 5 分钟是明示偏差 | 第 3.4 节 |
| 退款约束(11/11 补充) | 原订单须 `SUCCESS`、累计不超过实付、单笔大于 0.01 元、失败后同号重提;退款期限没写 | 期限仍待易宝确认 | 第 3.7 节 |
| 对账文件(11/11 补充) | `bill-trade-day-download`(`/yos/v1.0/std/bill/tradedaydownload`),参数 `merchantNo`、`dayString`、`dataType`(`merchant` / `platform`);平台商编下载的文件含全部入驻商户;生成时间和可下载范围没写 | 生成时间仍待易宝确认(Q21) | P8 每日对账(第 13.5 节);第 7.1 节记了下载口径 |
| 沙箱申请(11/11 补充) | 应用和私钥要找易宝技术支持申请并开通产品;配额文档没有 | 配额仍待易宝确认 | 第 21 节 |不在本设计范围
- 分账、归集、资金方案、循环收款池、提现、余额(GPAY-04—GPAY-21 的资金类)。对账只做第 13.5 节的收款、退款逐笔核对(P8),分账账单、资金账单核对不在第一阶段。 - 公众号 / 小程序 / 支付宝预下单(GPAY-07)。 - 部署执行、采购、改服务器、开公网(部署方案另行审批)。 - 真实扣款和退款:只用易宝沙箱或测试商户。 - 入网(进件):门店、教练、供应链、商户池商户的入网走服务商入网接口,第一阶段不加接口(产品负责人 11/11)。 - 转账和提现(产品负责人 11/11):系统记录门店、教练、供应商、品牌总部各自应得的金额;到提现时间点由品牌总部按应得金额转给门店、教练、供应商,再自动提现到对方账户。后续阶段再设计;品牌总部转给对方用“转账”接口,**不用余额分账**。第一阶段收款、退款接口里的分账字段继续一律拒绝。后续会用到的易宝接口(只记出处,现在不设计):转账下单 `POST /rest/v1.0/account/transfer/b2b/order`(在线文档 `docs-v3/api/options_rest_v1.0_account_transfer_b2b_order.md`),结果通知 `account.business.transfer-result`;提现下单 `POST /rest/v1.0/account/withdraw/order`(Skill 的 `withdraw-order`)。
API REFERENCE 13.2.1.1payment-service-B1
B1 支付结果通知支付设计
易宝把支付结果通知我们;我们核对无误并存好以后,才回复易宝收到。
契约状态:设计稿实现状态:设计未实现;基线:已实现(#12、#14);新设计不等于已验收真实接口验收:未经沙箱验收
POST
/api/v1/notify/yeepayDESIGN ONLY · NO LIVE CALLi
设计稿,未实现,未经沙箱验收
字段、规则、错误和有条件决定取自固定设计提交;只作展示,不运行请求或模拟成功。
- 仅静态合成示例;设计未实现、未经沙箱验收;不启用模拟成功,不发送 HTTP。
01接口说明
业务端 / 模块支付服务(易宝同款) / B 接收易宝通知
请求格式来源未定义
鉴权与权限易宝RSA数字信封解密、对原始明文验签,并核对商户/订单/金额;落库后应答(第11.1节)。 · 设计展示,禁止网络请求
技术服务归属(元信息)支付服务
易宝 → 本服务目录引用不授予调用权限。
来源业务约束
- 未在设计稿明确的字段、类型、必填性和响应层级保持未定义,不根据示例反推 schema。
- 设计稿未列数字信封完整请求字段和解密后完整业务字段;仅保留明确文字。
02请求头 0 个字段
来源没有可展开的字段定义。完整约束可在「来源与状态」查看。
03请求参数 按来源列示,未明确部分不补造
来源没有可展开的字段定义。完整约束可在「来源与状态」查看。
04响应参数
验签、核对和同事务落库完成后纯文本应答;HTTP 200 + 纯文本 SUCCESS。未知订单只落摘要回执,不创建收款。
来源没有可展开的字段定义。完整约束可在「来源与状态」查看。
05错误码 沿用来源定义
| HTTP 状态 | 来源业务码 | 来源说明 |
|---|---|---|
400 | 来源未定义 | 畸形或坏签;HTTP 400 + 纯文本 FAIL。未知订单只落摘要回执,不创建收款。 |
503 | 来源未定义 | 持久化失败;保留重试;HTTP 503 + 纯文本 FAIL。未知订单只落摘要回执,不创建收款。 |
06来源与状态
契约状态:设计稿实现状态:设计未实现;基线:已实现(#12、#14);新设计不等于已验收真实接口验收:未经沙箱验收
sourceCommit
7d2ae11e91ecd073944f98473ef41a67cd0f6146查看原始契约、引用与状态记录
{
"contract": {
"parameters": [],
"responses": {
"200": {
"description": "验签、核对和同事务落库完成后纯文本应答;HTTP 200 + 纯文本 SUCCESS。未知订单只落摘要回执,不创建收款。",
"content": {
"text/plain": {
"schema": {
"type": "string"
},
"example": "SUCCESS"
}
}
},
"400": {
"description": "畸形或坏签;HTTP 400 + 纯文本 FAIL。未知订单只落摘要回执,不创建收款。",
"content": {
"text/plain": {
"schema": {
"type": "string"
},
"example": "FAIL"
}
}
},
"503": {
"description": "持久化失败;保留重试;HTTP 503 + 纯文本 FAIL。未知订单只落摘要回执,不创建收款。",
"content": {
"text/plain": {
"schema": {
"type": "string"
},
"example": "FAIL"
}
}
}
},
"sourceExtensions": {
"x-permission": "设计展示,禁止网络请求",
"x-source-sections": [
"3.1",
"11.1",
"13.1",
"19",
"20",
"22"
]
}
},
"status": {
"contract": "设计稿",
"implementation": "设计未实现;基线:已实现(#12、#14);新设计不等于已验收",
"realApiAcceptance": "未经沙箱验收"
},
"provenance": {
"sourceCommit": "7d2ae11e91ecd073944f98473ef41a67cd0f6146",
"sourceBlob": "74501663abc0df79dd867f39057b29e7cd1345b3",
"sourceUrl": "https://github.com/SmartPool-Dev/smartpool-payment-service/pull/17",
"paymentService": {
"code": "B1",
"group": "易宝通知入口",
"purpose": "易宝把支付结果通知我们;我们核对无误并存好以后,才回复易宝收到。",
"direction": "易宝 → 本服务",
"supplier": {
"name": "支付结果通知",
"id": "trade.pay-result",
"path": "发送到 notifyUrl;无固定供应商请求地址",
"documentId": "文档无 API ID"
},
"phase": "—(已有,不在新能力批次中改)",
"baselineStatus": "已实现(#12、#14);新设计不等于已验收",
"differences": [
"接收易宝事件,不虚构供应商固定请求地址。验签及同事务持久化后才应答。",
"支付结果通知默认只在成功时发送,FAIL / TIME_OUT 须在易宝商户交易服务配置另开;不依赖失败/过期通知,后台查原单兜底。该默认时机说明针对支付通知,不扩大到退款通知。",
"payerInfo 整个对象及其 bankId、accountName、bankCardNo、mobilePhoneNo、cardType、userID、buyerLogonId、ypAccountBookNo、appID、channelTrxId、bankPostscript 全部子字段不落日志、不推第二跳;顶层 userId、buyerLogonId、yeepayOpenId、bankCardNo 以及 enterprisePayInfo.enterpriseId 同样删除。channelTrxId 只保留后 4 位,完整值不落、不推。"
],
"openQuestions": [
{
"id": "易宝",
"question": "付款码 / 聚合码订单是否适用关单接口;同步返回缺 `payAmount` 的可信口径;沙箱白名单与配额;通知重试间隔与次数(Q20);对账文件(Q21);退款期限(Q4)",
"decision": "—",
"status": "待易宝确认(产品负责人线下问)",
"impact": "P2—P5、验收"
},
{
"id": "Q11",
"question": "付款人信息",
"decision": "不保留:日志和第二跳只留金额、支付方式、时间、渠道交易号后 4 位等对账字段(第 11.2、13.1 节)",
"status": "产品负责人已定 11/11",
"impact": "P1b(日志脱敏)、P7(推送)"
}
],
"sourceSections": [
{
"id": "3.1",
"title": "路径对照",
"body": "| 能力 | 易宝官方 | API ID / 文档更新 | 本服务路径(照抄) | 方法 / 请求格式 | 现状(c7d23d3) | 计划 PR |\n| --- | --- | --- | --- | --- | --- | --- |\n| 付款码收款 | `POST /rest/v1.0/aggpay/pay` | `348be29b…3bb4` / 2026-08-17 22:28:40 | `/rest/v1.0/aggpay/pay` | POST form | 内核已有,对外是 `/api/v1/payments/auth-code` JSON | P2 |\n| 本单二维码(聚合码) | `POST /rest/v1.0/aggpay/pay-link` | `b49db74d…14d1` / 2026-01-20 20:15:44 | `/rest/v1.0/aggpay/pay-link` | POST form | 未实现 | P3 |\n| 查收款订单 | `GET /rest/v1.0/trade/order/query` | `1fe6aa42…74eab` / 2026-03-13 17:27:49 | `/rest/v1.0/trade/order/query` | GET query | 内核已有,对外是 `/api/v1/payments/query` JSON | P2 |\n| 关闭订单 | `POST /rest/v1.0/trade/order/close` | `618b57b3…c85b` / 2025-03-03 11:46:37 | `/rest/v1.0/trade/order/close` | POST form | 只有内部关单队列,无公共路由 | P5 |\n| 申请退款 | `POST /rest/v1.0/trade/refund` | `35122e4a…76e8` / 2026-03-10 15:25:28 | `/rest/v1.0/trade/refund` | POST form | 未实现 | P4 |\n| 查退款 | `GET /rest/v1.0/trade/refund/query` | `ddb05a9b…0b26` / 2026-10-10 16:45:06 | `/rest/v1.0/trade/refund/query` | GET query | 未实现 | P4 |\n| 支付结果通知 | `trade.pay-result`(发往 notifyUrl) | 文档无 API ID | 本服务接收:`/api/v1/notify/yeepay`(沿用) | 易宝 → 本服务 | 已实现(#12、#14) | — |\n| 退款结果通知 | `trade.refund-result` | 文档无 API ID | 本服务接收:建议 `/api/v1/notify/yeepay/refund` | 易宝 → 本服务 | 当前回 FAIL/503 保留重试 | P4 |\n| 第二跳推送 | 无(本服务自有) | — | 调用方登记的地址 | 本服务 → 调用方 | 未实现 | P7 |\n\nAPI ID 全文:付款码 `348be29b03b2430fa8910175524d3bb4`;聚合码 `b49db74dd1fe4099836cf9e7b5d114d1`;查单 `1fe6aa427dc941cc8228fe9700a74eab`;关单 `618b57b3a47d4447bf009e261e73c85b`;退款 `35122e4a4b5b406797243b86083376e8`;查退款 `ddb05a9b714b4edba112c0eab0705b26`。实现时以当天重新拉取的官方文档为准,变化写进 PR。\n\n不使用:旧 `/rest/v1.0/sys/trade/*` 接口族;不用 `/aggpay/pre-pay` 代替付款码或聚合码。"
},
{
"id": "11.1",
"title": "易宝 → 本服务(第一跳)",
"body": "- 支付通知沿用 `/api/v1/notify/yeepay`:RSA 数字信封解密、对原始明文验签、核对商户 / 订单 / 金额,回执、状态、成功事实、版本和事件同事务提交后才回 HTTP 200 + 纯文本 `SUCCESS`;畸形 / 坏签 400 + `FAIL`;持久化失败 503 + `FAIL`;未知订单只落摘要回执,不创建收款。#14 的失败 / 过期通知金额兼容保留。易宝支付结果通知**默认只在支付成功时发**,订单过期(`TIME_OUT`)和支付失败(`FAIL`)要在易宝商户交易服务配置里另开才会通知(Claude 11/11 按官方 Skill 和在线文档核对);本服务**不依赖失败和过期通知**,没开这个配置时靠后台查原单了结(现有轮询就是这样),#14 的兼容只在开了配置时用到。\n- 退款通知(P4):建议新路径 `/api/v1/notify/yeepay/refund`,同样的落库后应答规则;`status` 为 SUCCESS / FAILED / CANCEL;更新退款单和占额。\n- 发给易宝的 `notifyUrl` 一律是本服务入口。切换环境、灾备时回调域名保持稳定(部署方案第七节)。"
},
{
"id": "13.1",
"title": "记什么",
"body": "新表 `payment_exchange_logs`,只追加:\n\n| 字段 | 说明 |\n| --- | --- |\n| `log_uid` | **记录的稳定标识**:应用在写之前生成的 UUIDv7(时间有序、随机部分保证多节点不重复),数据库和文件写同一个值;数据库唯一索引。数据库写失败时文件里照样有它,两份按它一一对应 |\n| `node` | 写这条记录的节点标识(和文件名里的一致) |\n| `id`、`created_at` | `id` 是数据库自增主键,只在库内用,**不写进文件、不作为两份之间的关联号**;`created_at` 写入时间(毫秒,应用生成,两份相同) |\n| `trace_id` | 一次调用方请求贯穿三段的关联号;后台任务自己生成 |\n| `segment` | `caller`(调用方 ↔ 本服务)、`channel`(本服务 ↔ 易宝)、`notify`(易宝 → 本服务)、`push`(本服务 → 调用方,第二跳);**只在文件里**另有 `state`(状态事件行,第 13.3 节) |\n| `source` | 只在数据库:`direct`(正常写入)/ `file_backfill`(补写任务从文件补插) |\n| `backfilled`、`backfilled_for` | 只在文件:补写任务补进来的行标 `backfilled=true`;替已下线节点补的另标 `backfilled_for=<节点>` |\n| `operation` | `aggpay.pay`、`aggpay.pay-link`、`order.query`、`order.close`、`refund`、`refund.query`、`pay-result`、`refund-result` 等 |\n| `app_ref`、`brand_ref`、`store_ref` | 调用方和授权范围 |\n| `bill_no`、`order_id`、`payment_ref`、`refund_request_id` | 查整条链路用的号码 |\n| `http_method`、`path`、`http_status` | |\n| `result_code`、`result_status` | 易宝 `code` / `status` 或本服务 `error.code` |\n| `outcome` | 本服务判定:`accepted`、`succeeded`、`failed`、`unknown`、`rejected`、`conflict` 等 |\n| `latency_ms` | 耗时 |\n| `request_body`、`response_body` | 脱敏后的完整请求和返回(JSON 文本) |\n| `body_sha256` | 原始字节摘要(脱敏前),用于核对 |\n| `related_trace_id` | 回调、后台查单、关单 worker、第二跳生成自己的 `trace_id`,这里填触发它的原请求 `trace_id`(能找到时);找不到的靠 `order_id` / `payment_ref` 串 |\n| `auth_result` | 第①段:`ok` / `scope_denied`,以及和 401 `details.reason` 同一套的 `invalid_content_type` / `query_not_allowed` / `missing_auth_header` / `timestamp_out_of_window` / `non_canonical` / `invalid_signature` / `nonce_reused` / `nonce_unavailable`(第 4.3 节) |\n| `dispatch_stage` | 第②段:`not_sent`(预算不足等未发出)/ `sent` / `response_received` / `timeout_after_send` |\n| `signature_result` | 第②段应答 `x-yop-sign` 验签、第③段通知验签:`ok` / `bad` / `missing` |\n| `notification_key` | 第③段:通知去重键(现有 `channel_notifications.notification_key`) |\n| `match_result` | 第③段:`matched` / `unknown_order` / `identity_mismatch` / `amount_mismatch` |\n| `dedupe_result` | 第③段:`first` / `duplicate` |\n| `persist_result` | 第③段:`committed` / `rolled_back` |\n| `ack` | 第③段回给易宝的应答:HTTP 状态 + `SUCCESS` / `FAIL` |\n\n部署清单 C1—C3 的逐项对应:C1 调用方→支付 = 第①段(`auth_result`、`request_body`、`response_body`、`app_ref`、`latency_ms`、`trace_id`);C2 支付→易宝 = 第②段(`operation`、`order_id`、`dispatch_stage`、`result_code`、`signature_result`、`latency_ms`、`outcome=unknown` 表示未明);C3 易宝→支付 = 第③段(`notification_key`、`signature_result`、`match_result`、`dedupe_result`、`persist_result`、`ack`、`latency_ms`)。\n\n脱敏样例(合成数据,非真实订单):\n\n```text\nsegment=caller operation=aggpay.pay trace_id=t-01 order_id=100000000000000123_1 auth_result=ok\n request_body={\"merchantNo\":\"<商编>\",\"orderId\":\"100000000000000123_1\",\"orderAmount\":\"30.00\",\"authCode\":\"****1234\",...}\n response_body={\"code\":\"00000\",\"status\":\"PROCESSING\",...} http_status=200 outcome=unknown latency_ms=4120\nsegment=channel operation=aggpay.pay trace_id=t-01 dispatch_stage=response_received signature_result=ok result_code=00000 result_status=PROCESSING\nsegment=channel operation=order.query trace_id=t-07 related_trace_id=t-01 result_code=OPR00000 result_status=SUCCESS signature_result=ok\nsegment=notify operation=pay-result trace_id=t-09 order_id=100000000000000123_1 notification_key=<摘要> signature_result=ok\n match_result=matched dedupe_result=first persist_result=committed ack=200 SUCCESS\n```\n\n- “所有请求和返回的数据都要记录”:按上表记完整报文,只做下面的脱敏。鉴权失败的请求也记(不认领 nonce、不进业务),但不记请求体;为防刷请求撑爆表,鉴权失败的写入按来源 IP + `app_ref` 限速(建议每分钟每来源前 60 条全记,之后每分钟只记 1 条汇总并带计数),超过阈值发告警(第 14 节“鉴权失败激增”)。\n- 脱敏:`authCode` 只留后四位(日志里写 `****1234`);签名(`X-SP-Signature`、`x-yop-sign`、`Authorization`)、密钥、证书、数字信封密文不记;**付款人信息不落日志**(Q11 已定):付款人标识:顶层的 `userId`、`buyerLogonId`、`yeepayOpenId`、`bankCardNo`,以及 `payerInfo` 整个对象(子字段 `bankId`、`accountName`、`bankCardNo`、`mobilePhoneNo`、`cardType`、`userID`、`buyerLogonId`、`ypAccountBookNo`、`appID`、`channelTrxId`、`bankPostscript`),以及 `enterprisePayInfo.enterpriseId`,在写日志前删除(判断标准同第 3.3 节);`channelTrxId` 只留后 4 位;只留对账需要的金额、支付方式、时间、渠道交易号后 4 位。注意区分:禁止出现在对外返回里的是**付款码**尾号;**渠道交易号后 4 位**(`channel_trade_no_last4`,GPAY02-07)是允许返回的,不要一起删掉。\n- 写入时机:第①段在返回前写;第②段在渠道调用返回或超时后写;第③段在应答前写;写日志失败不改变资金判定,但要告警(不能因为日志写不进去就把成功说成失败)。"
},
{
"id": "19",
"title": "待定问题与决定",
"body": "11/11 产品负责人定了全部非易宝项。“产品负责人已定”立即生效;“Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效”这几条由 Lihao 在 #17 提异议,有异议就按他的意见改文档后重新复审。只有 Q15 挡 P1,其余到 P2、P4、P7 才用到。\n\n| # | 问题 | 决定 | 状态 | 影响 |\n| --- | --- | --- | --- | --- |\n| Q1 | 返回业务结果对象还是完整 YOP 网关响应 | 只返回易宝业务结果对象(第 3.3、6.1 节) | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P2 |\n| Q2 | 是否加本服务响应签名 | 第一阶段不加(第 6.1 节) | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P2 |\n| Q3 | `merchantNo` 是否必填 | 必填(第 3.3 节) | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P2 |\n| Q4 | 并行期怎么切、序号位数 | 按门店整体切换;序号 1—6 位、不补零(第 7 节) | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P2 |\n| Q5 | `expiredTime` 范围 | 付款码 1—15 分钟、不传补 15 分钟;二维码 1—60 分钟、不传补 5 分钟(第 3.3、3.4 节) | 产品负责人已定 11/11 | P2、P3 |\n| Q6 | 二维码 `scene` 默认值 | 不传时补 `{\"WECHAT\":\"OFFLINE\",\"ALIPAY\":\"OFFLINE\"}`(第 3.4 节) | 产品负责人已定 11/11 | P3 |\n| Q7 | 二维码换新、隐式关前代 | 去掉 `renew`,POS“关单 → 新 orderId”;不做隐式关前代,未关旧码时 409 拦住(第 3.4、10 节) | 产品负责人已定 11/11;POS 流程部分同 Q1 的异议期 | P3、P5 |\n| Q8 | 退款 / 查退款定位方式 | 只按 orderId(第 3.7、3.8 节) | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P4 |\n| Q9 | 退款失败、`SUSPEND` | 不开通补充卡信息退款;失败类都标待核、资金类告警、转人工,不自动重退、不自动结束退款(第 3.7 节) | 产品负责人已定 11/10 | P4 |\n| Q10 | `biz_no`、`order_kind` | 不进易宝字段,内部按 bill_no 关联(第 7 节) | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P2 |\n| Q11 | 付款人信息 | 不保留:日志和第二跳只留金额、支付方式、时间、渠道交易号后 4 位等对账字段(第 11.2、13.1 节) | 产品负责人已定 11/11 | P1b(日志脱敏)、P7(推送) |\n| Q12 | 告警接收 | 专门的 Slack 频道;接收人产品负责人、Lihao;资金类 15 分钟内响应,其他当天;webhook 只放 `.env`,P6 前提供(第 14.2 节) | 产品负责人已定 11/11 | P6 |\n| Q13 | PR 顺序 | P1→P7(第 17 节);11/11 暂定加 P1b(紧跟 P1)和 P8(P7 之后) | 产品负责人已定 11/11 | 全部 |\n| Q14 | 新错误码名字和 HTTP 状态 | 按第 5 节 | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P2 起 |\n| Q15 | 签名 v2 逐字节规则 | 按第 4.3 节;`Content-Type` 只认 `application/x-www-form-urlencoded`,不带 charset | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | **P1** |\n| Q16 | 第二跳是否推 `payment.unknown` | 第一阶段不推(第 11.2 节) | 产品负责人已定 11/11 | P7 |\n| Q17 | 通过标准数值 | 按第 21.3 节 | 产品负责人已定 11/11 | 验收 |\n| Q18 | `REFUND_IN_PROGRESS`、`REFUND_AMOUNT_EXCEEDED` | 按第 3.7、5 节 | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P4 |\n| Q19 | 第二跳推送签名 v2 | 按第 11.2 节,POS 侧同步实现 | Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效 | P7 |\n| 报文存储 | 报文怎么存、存多久 | 数据库+文件双写,两份都长期保留,不设清理;文件和库不同盘、每天复制到服务器外(第 13.2、13.3 节) | 产品负责人已定 11/11 | P1b、部署 |\n| 报文记录批次 | 报文记录何时做 | 从 P6 提到 P1b,内部只读查询一起提前(第 17 节) | 产品负责人暂定 11/11 | P1b |\n| 每日对账 | 上线前是否加对账 | 加 P8 每日对账,收真钱前置;差错只记录告警、不自动改资金状态(第 13.5 节) | 批次暂定;“不自动改状态”已定 11/11 | P8 |\n| 判断顺序(11/11 复审) | `Content-Type` 不对回什么 | 统一 401,在验签前判断(第 3.2、4.3 节) | 文档前后统一,属 Q15 范围,异议期同 Q15 | **P1** |\n| orderId 序号写法 | 序号能否 0 开头 | 不能,`_01` 回 422(第 3.3、7 节),与 Q4 一致 | 文档前后统一 | P2 |\n| 401 原因 | 401 能否分清原因 | `details.reason` 八个取值(含 `nonce_unavailable`)、日志同一套、带 `WWW-Authenticate`;调用方自己生成一次表单字节再签名发送;向量 11 组(第 4.3 节) | Lihao 11/11 要求;名字按他举例,异议期同 Q15 | **P1** |\n| 同步返回里的付款人字段 | 付款码、查单的同步返回按 Q1 原样会带上易宝给的付款人字段(`payerInfo` 等),要不要也去掉 | 去掉,清单见第 3.3 节,其余字段照旧(第 1 节第 4 处例外) | 产品负责人已定 11/11 12:49(亚利桑那) | P2 |\n| 备份恢复后收款怎么重新开放 | 恢复后当时所有在用收款入口(A1、A2,并行期还有旧付款码接口 E1)何时开放,系统要不要按账单拦 | 先停后开:比对清单交到人手里再开,停的期间收现金;不做按账单拦截,通知门店写进恢复手册(第 13.3 节) | 产品负责人已定 11/11 14:11(亚利桑那) | P1b、部署方案 |\n| 旧接口 E1、E2 的付款人信息 | 旧 `/api/v1/payments/auth-code`、`/api/v1/payments/query` 返回里带不带 | 现状:**不带**。两者都返回本服务自己的 `PaymentResource`(基线 `c7d23d3` 的 `app/Http/Resources/PaymentResource.php`),字段是内部单号、金额、状态、`channel_trade_no_last4` 等,不透传易宝返回,没有 `payerInfo`、`userId`、`buyerLogonId` 等。建议:不用改,在并行期回归里加一条“旧接口返回不出现付款人字段” | 现状已核对;建议待产品负责人确认 | P2 回归 |\n| 渠道交易号后 4 位放哪 | 查单是否加 | 查单不加;只在 facts 和第二跳推送给(第 3.5、12、17 节) | 文档前后统一 | P7 |\n| 商户结构 | 品牌总部、门店、教练等的易宝类型 | 门店是品牌总部下的入驻商户(发起方商编 = 平台商编);按商编可配置(第 7.1 节) | 门店:产品负责人已定 11/11;教练、供应链、商户池中的商户:**待确认** | P2 配置 |\n| 易宝 | 付款码 / 聚合码订单是否适用关单接口;同步返回缺 `payAmount` 的可信口径;沙箱白名单与配额;通知重试间隔与次数(Q20);对账文件(Q21);退款期限(Q4) | — | **待易宝确认**(产品负责人线下问) | P2—P5、验收 |"
},
{
"id": "20",
"title": "易宝官方 Skill 核对结果(11/10 产品负责人建议)",
"body": "依据:`github.com/Yeepay-Open-Platform/yeepay-skills`,技能 `yeepay-payment-integration` v1.5.0,固定提交 `ccb7783a7e1eab63f77b4f78e470c617499ab440`(和 #16 官方向量是同一提交)。只读 `references/`,没有运行 `scripts/`,没有使用任何密钥。另对照易宝在线文档(11/10 拉取)。\n\n| 待确认点 | Skill / 文档怎么说 | 结论 | 对本设计的影响 |\n| --- | --- | --- | --- |\n| 付款码、聚合码订单能不能调关单 | Skill 的付款码、聚合码场景只列“下单 + 查单”,没有关单;`api-index.yaml` 里没有关单接口。在线关单文档(`618b57b3…c85b`,2025-03-03)没有提到付款码 / 聚合码,既没说适用也没说不适用,只写了合单子单不支持关单(`OPR00093`) | **仍未确认**,Skill 回答不了 | 第 3.6 节不变:关单结果只当提示,靠查原单定终态;仍须向易宝确认或实测 |\n| 通知重试间隔和次数(易宝答复 Q20) | 《结果通知机制说明》:未按约定应答就自动重试,“具体频次因产品/场景略有差异,以控制台发送记录为准”;控制台可查询、手工重发、换地址重发 | **没有固定数字** | 设计不依赖重试频次:落库后才应答、重复通知幂等、主动查单兜底(第 9、11 节)。上线手册加一条:通知异常时到控制台“结果通知”查发送记录、手工重发 |\n| 通知成功应答 | RSA:HTTP 200 + 纯文本 `SUCCESS`;SM2:200 + `{\"result\":\"SUCCESS\"}` 并签名 | 和现有实现一致 | 无 |\n| 回调和查单不一致 | 《结果通知机制说明》:“回调与查单不一致时以查单为准” | 和本设计一致的部分:终态靠查单确认 | 本设计更保守:和**已确认终态**矛盾时不直接改,标待核(GPAY 已定规则 6),不冲突 |\n| 退款 `SUSPEND` | 《退款》:只有商户开通了“补充卡信息退款”才会停在 `SUSPEND`,需调 `trade/refund/supply` 补卡或 `trade/refund/end` 结束;**没开通时**,原路退款失败**且能取到支付卡信息**才会自动转打款退款,转打款仍失败(或取不到卡信息)钱退回商户易宝账户 | 第一阶段不开通该服务,正常不会出现 `SUSPEND` | 第 3.7 节:收到 `SUSPEND` 说明商户配置和约定不符,标待核、告警,不自动重退、不自动调 supply / end(Q9 已按此定:不开通该服务) |\n| 退款失败后的资金去向 | 同上:没开通补卡退款时,原路失败且转打款没发生或也失败,钱回到商户易宝账户 | 门店直收要有对应账务处理 | 告警由 P4 写入、P6 外发;每日对账(P8)核对退款;退款失败后用**同一个** `refundRequestId` 重试(《退款》易错点) |\n| 付款码必传字段 | 《被扫支付》:`terminalId`、`userIp`、`scene=OFFLINE` 必传;`expiredTime` 不传默认 24 小时 | 在线文档:`scene` 条件必填(按渠道,银联除外),`terminalId` 非必填(线下面对面场景请传);Skill 两项都写必传 | 第 3.3 节:微信、支付宝 `scene=OFFLINE` 必填(符合在线文档);`terminalId` 按 Skill 和线下面对面场景收紧为必填 |\n| 付款码同步返回 | 《被扫支付》:同步可能是 `SUCCESS` 或处理中,处理中必须轮询查单,不可判失败或重复下单 | 和现有实现一致 | 无 |\n| 聚合码的 `payWay`、`userIp` | Skill《主扫支付(聚合码)》写 `payWay=USER_SCAN`、`userIp` 按需;在线 pay-link 文档(2026-01-20)没有这两个字段 | 两份官方材料不一致 | 先按在线文档不传(沿用 PAY-r7 字段核对的处理),沙箱联调时确认;如网关要求再改 |\n| 聚合码前置条件 | 开通“用户扫码支付宝线上”“用户扫码微信线上”,完成子商户认证,配置公众号 appid、appSecret、支付授权目录(`/rest/v2.0/aggpay/wechat-config/add`) | 与 PAY-r7 开工前要办一致 | 列入 P3 前置条件,由产品负责人对易宝办 |\n| 沙箱能验什么 | 《沙箱环境联调测试》:沙箱“主要支持 YOP 网关校验、商户回调通知”,是模拟环境,“所有返回码及业务逻辑以正式环境为准” | 关单适用性、真实 `payAmount`、真实失败码**沙箱证明不了** | 验收里这几项沙箱结果只算网关和报文验证,渠道能力本身标“待核 / 阻塞”,靠易宝书面答复补证据。正式环境验证**不属于本轮验收**,也不是自动的下一步;要不要做、怎么做由产品负责人另行决定(不做真实扣款、退款的红线不变) |\n| 易宝回调来源限制 | 《回调网络配置》:出口 IP 会变,推荐域名白名单(`out.yeepay.com`),只能用 IP 时每小时解析一次同步规则 | — | 部署清单 A3 补充:不要把易宝回调 IP 写死 |\n| 同步返回缺 `payAmount` 的口径、YOP 完整响应与签名、沙箱配额 | Skill 未涉及 | 仍未确认 | 维持第 6.2 节和 Q1 |\n| 关单返回码(11/11 补充) | 在线关单文档另列 `OPR18010`、`OPR18013`、`OPR18015`、`OPR13003`、`P00013`、`P00016`、`OPR00024`、`OPR00025` | 已逐个定处理 | 第 3.6 节返回码表 |\n| 支付通知何时发(11/11 补充) | 默认只在支付成功时发,过期和失败要在商户交易服务配置里另开 | 不依赖失败 / 过期通知 | 第 11.1 节:靠查原单了结 |\n| 通知 `payerInfo` 子字段(11/11 补充) | `bankId`、`accountName`、`bankCardNo`、`mobilePhoneNo`、`cardType`、`userID`、`buyerLogonId`、`ypAccountBookNo`、`appID`、`channelTrxId`、`bankPostscript` | 全部不落日志、不推;`channelTrxId` 只留后 4 位 | 第 11.2、13.1 节 |\n| 聚合码 `expiredTime` 默认(11/11 补充) | 不传时易宝默认 1 小时(付款码 24 小时) | 本服务补 5 分钟是明示偏差 | 第 3.4 节 |\n| 退款约束(11/11 补充) | 原订单须 `SUCCESS`、累计不超过实付、单笔大于 0.01 元、失败后同号重提;退款期限没写 | 期限仍待易宝确认 | 第 3.7 节 |\n| 对账文件(11/11 补充) | `bill-trade-day-download`(`/yos/v1.0/std/bill/tradedaydownload`),参数 `merchantNo`、`dayString`、`dataType`(`merchant` / `platform`);平台商编下载的文件含全部入驻商户;生成时间和可下载范围没写 | 生成时间仍待易宝确认(Q21) | P8 每日对账(第 13.5 节);第 7.1 节记了下载口径 |\n| 沙箱申请(11/11 补充) | 应用和私钥要找易宝技术支持申请并开通产品;配额文档没有 | 配额仍待易宝确认 | 第 21 节 |"
},
{
"id": "22",
"title": "不在本设计范围",
"body": "- 分账、归集、资金方案、循环收款池、提现、余额(GPAY-04—GPAY-21 的资金类)。对账只做第 13.5 节的收款、退款逐笔核对(P8),分账账单、资金账单核对不在第一阶段。\n- 公众号 / 小程序 / 支付宝预下单(GPAY-07)。\n- 部署执行、采购、改服务器、开公网(部署方案另行审批)。\n- 真实扣款和退款:只用易宝沙箱或测试商户。\n- 入网(进件):门店、教练、供应链、商户池商户的入网走服务商入网接口,第一阶段不加接口(产品负责人 11/11)。\n- 转账和提现(产品负责人 11/11):系统记录门店、教练、供应商、品牌总部各自应得的金额;到提现时间点由品牌总部按应得金额转给门店、教练、供应商,再自动提现到对方账户。后续阶段再设计;品牌总部转给对方用“转账”接口,**不用余额分账**。第一阶段收款、退款接口里的分账字段继续一律拒绝。后续会用到的易宝接口(只记出处,现在不设计):转账下单 `POST /rest/v1.0/account/transfer/b2b/order`(在线文档 `docs-v3/api/options_rest_v1.0_account_transfer_b2b_order.md`),结果通知 `account.business.transfer-result`;提现下单 `POST /rest/v1.0/account/withdraw/order`(Skill 的 `withdraw-order`)。"
}
],
"requestFields": [],
"responseFields": [],
"uncertainty": [
"未在设计稿明确的字段、类型、必填性和响应层级保持未定义,不根据示例反推 schema。",
"设计稿未列数字信封完整请求字段和解密后完整业务字段;仅保留明确文字。"
],
"displayFields": [],
"keyRules": [],
"authDescription": "易宝RSA数字信封解密、对原始明文验签,并核对商户/订单/金额;落库后应答(第11.1节)。"
}
},
"diagnostics": {
"networkEnabled": false,
"documentationOnly": true
},
"businessRules": [
"接收易宝事件,不虚构供应商固定请求地址。验签及同事务持久化后才应答。",
"支付结果通知默认只在成功时发送,FAIL / TIME_OUT 须在易宝商户交易服务配置另开;不依赖失败/过期通知,后台查原单兜底。该默认时机说明针对支付通知,不扩大到退款通知。",
"payerInfo 整个对象及其 bankId、accountName、bankCardNo、mobilePhoneNo、cardType、userID、buyerLogonId、ypAccountBookNo、appID、channelTrxId、bankPostscript 全部子字段不落日志、不推第二跳;顶层 userId、buyerLogonId、yeepayOpenId、bankCardNo 以及 enterprisePayInfo.enterpriseId 同样删除。channelTrxId 只保留后 4 位,完整值不落、不推。"
],
"issues": [
"未在设计稿明确的字段、类型、必填性和响应层级保持未定义,不根据示例反推 schema。",
"设计稿未列数字信封完整请求字段和解密后完整业务字段;仅保留明确文字。"
]
}