设计稿,未实现,未经沙箱验收。只作接口走查,不发送真实请求。基线已有能力单独列明,不代表此设计已经落地。
设计来源:支付服务 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批次暂定;对账只记录差错和告警,不自动改资金状态。
A3 · 对应易宝接口
易宝名称查单
接口标识trade-order-query
在线文档编号1fe6aa427dc941cc8228fe9700a74eab
易宝路径 / 事件/rest/v1.0/trade/order/query
谁调谁调用方 → 本服务
基线现状内核已有,对外仍是旧 JSON 接口
开发批次(计划)P2
和易宝不一样的地方
- 调用方使用本服务签名而非 YOP,易宝 SDK 不能零改动直连。
- 易宝回调先到本服务再签名推给调用方,不是字节级透传。
- 安全错误使用本服务 error 外层,不冒充易宝 code;业务结果不加 data/meta。
- 只支持门店直收;不支持的官方字段明确拒绝,未知字段也拒绝。
- 门店已确认是品牌总部下的入驻商户(SETTLED_MERCHANT);默认 parentMerchantNo 为品牌总部的平台商编,与 merchantNo 不同。标准商户同编是另一种按商编配置;教练、供应链、商户池类型仍待确认,第一阶段不收款,不默认任何类型。
- 产品负责人11/11 12:49已定:同步返回删除第3.3节付款人字段,其余易宝字段原样原类型;理由是付款人信息不保留。顶层完整channelTrxId不截短,日志及推送的后4位规则不用于同步返回。
查询行为(建议)
- 只查本应用授权范围内、本服务发起过的订单;不认识的 orderId 回 404 `NOT_FOUND`,不替调用方查别人的单。
- 每次请求在预算内实时查易宝原账户、原商户、原订单;同一订单有进行中的查询时,等它的结果(最多到本次预算),不并发打易宝。
- 查到的结果和本地已确认的事实一致:HTTP 200,返回易宝查单业务结果(官方返回表的全部字段原样原层级原类型,第 6.2 节)。不加本服务自己的字段(包括 `channel_trade_no_last4`,它只在 facts 接口和第二跳推送里给,第 17 节 GPAY02-07);删掉付款人字段,清单和规则同第 3.3 节(产品负责人 11/11 12:49 亚利桑那已定)。
- 和本地已确认事实矛盾(如本地已成功、这次查到 FAIL):不返回渠道结果,回 409 `EVIDENCE_CONFLICT`(第 5 节),内部标待核、告警。
- 超时、坏签、缺必要字段:504 / 502(第 5 节),不返回半截结果。
入口判断顺序(11/11复审统一)
- 本页是 GET,参数放在规范查询串中,不执行 POST 的 Content-Type/query 检查,从检查鉴权头和时间戳开始。
- 鉴权头齐全 → 否则 401,`missing_auth_header`;时间戳在 ±300 秒内 → 否则 401,`timestamp_out_of_window`。
- 规范性:严格解析(每对一个 `=`、编码规范、`+` 拒绝、重复键拒绝)→ 否则 401,`non_canonical`。
- 验签 → 否则 401,`invalid_signature`。
- 认领 nonce(600 秒窗口)→ 重用 401,`nonce_reused`;nonce 表抢锁失败 401,`nonce_unavailable`。
- 授权范围(`merchantNo` 等是否属于本应用)→ 403 `SCOPE_DENIED`。
- 字段白名单和取值校验 → 422 `VALIDATION_FAILED`;之后才进业务、调渠道。
渠道交易号后4位的位置
- A3原样返回易宝业务结果,不添加channel_trade_no_last4;该本服务字段只在facts和第二跳推送提供,成功单有值,其余null(第3.5、12、17节)。
401原因与响应头
- 401 的机器可读原因(Lihao 11/11 要求,POS 据此分清表单配置问题和签名问题):返回 `{"error":{"code":"UNAUTHENTICATED","message":"…","details":{"reason":"<原因>"}}}`,`reason` 取上面 1—5 步的值之一:`invalid_content_type`、`query_not_allowed`、`missing_auth_header`、`timestamp_out_of_window`、`non_canonical`、`invalid_signature`、`nonce_reused`,另加下面归并规则里的 `nonce_unavailable`。日志第①段 `auth_result` 用同一套取值(第 13.1 节)。`reason` 只说哪一步没过,不回显期望的签名或待签串。归并规则:鉴权头缺失、重复、格式不对(时间戳不是数字、nonce 长度不对等),以及新接口上 `X-SP-Sign-Version` 缺失或不是 `2`,都算 `missing_auth_header`;应用标识不认识或已停用算 `invalid_signature`(不暴露应用是否存在);nonce 表抢锁失败(第 5 节保留的那种 401)也回 401,但不算重放,`reason` 用 `nonce_unavailable`(第八个值,日志同名),调用方可以换新 nonce 重签再发。401 响应带 `WWW-Authenticate: SP-Sign version="2"` 头。
同步返回付款人信息处理
- 去掉的付款人字段(产品负责人 11/11 12:49 亚利桑那已定,第 1 节第 4 处例外):返回前删掉顶层的 `userId`、`buyerLogonId`、`yeepayOpenId`、`bankCardNo`,以及 `payerInfo` 整个对象(子字段 `bankId`、`accountName`、`bankCardNo`、`mobilePhoneNo`、`cardType`、`userID`、`buyerLogonId`、`ypAccountBookNo`、`appID`、`channelTrxId`、`bankPostscript`),出现就删,没有就不管;其余字段照旧原样原类型。删除只发生在返回给调用方的那一份;本服务判定用的渠道交易号后 4 位在删除前取出、存进收款单(只在 facts 和推送里给)。另删查单返回 `enterprisePayInfo` 里的 `enterpriseId`(付款企业的账户 id,只在支付宝企业码支付时出现),对象里其余字段保留。判断标准:能认出具体付款人或其账户的删(账号、卡号、手机号、姓名、openid、企业账户 id);只说明支付方式的不删。顶层的 `channelTrxId`(完整渠道交易号)、`appID`、`cardType`、`payBank` 是易宝自己的顶层字段,原样返回,不截短、不删(日志里“`channelTrxId` 只留后 4 位”的规则只管日志和推送,不用于同步返回)。查单里的 `cardType`、`bankId` 在 `payerInfo` 里,跟着整个对象一起删,和付款码顶层保留的不一样,收银台要用请 Lihao 提出。这份清单来自易宝通知文档、11/11 核对和 Claude 第 8 轮对在线返回表的复核;P2 实现前按当天的付款码、查单在线返回表再逐个核对,P4 实现前对退款、查退款(含 `channelReceiverInfo`)同样核对,按上面的标准处理,变化写进对应 PR。
未完整定义的字段说明
以下为来源点名的内容或脱敏规则,不补造协议字段名、返回位置、类型或媒体格式。
| 位置 | 来源内容 / 中性标签 | 说明 |
|---|---|---|
| 返回 | 同步返回删除清单 | 去掉的付款人字段(产品负责人 11/11 12:49 亚利桑那已定,第 1 节第 4 处例外):返回前删掉顶层的 `userId`、`buyerLogonId`、`yeepayOpenId`、`bankCardNo`,以及 `payerInfo` 整个对象(子字段 `bankId`、`accountName`、`bankCardNo`、`mobilePhoneNo`、`cardType`、`userID`、`buyerLogonId`、`ypAccountBookNo`、`appID`、`channelTrxId`、`bankPostscript`),出现就删,没有就不管;其余字段照旧原样原类型。删除只发生在返回给调用方的那一份;本服务判定用的渠道交易号后 4 位在删除前取出、存进收款单(只在 facts 和推送里给)。另删查单返回 `enterprisePayInfo` 里的 `enterpriseId`(付款企业的账户 id,只在支付宝企业码支付时出现),对象里其余字段保留。判断标准:能认出具体付款人或其账户的删(账号、卡号、手机号、姓名、openid、企业账户 id);只说明支付方式的不删。顶层的 `channelTrxId`(完整渠道交易号)、`appID`、`cardType`、`payBank` 是易宝自己的顶层字段,原样返回,不截短、不删(日志里“`channelTrxId` 只留后 4 位”的规则只管日志和推送,不用于同步返回)。查单里的 `cardType`、`bankId` 在 `payerInfo` 里,跟着整个对象一起删,和付款码顶层保留的不一样,收银台要用请 Lihao 提出。这份清单来自易宝通知文档、11/11 核对和 Claude 第 8 轮对在线返回表的复核;P2 实现前按当天的付款码、查单在线返回表再逐个核对,P4 实现前对退款、查退款(含 `channelReceiverInfo`)同样核对,按上面的标准处理,变化写进对应 PR。 |
后续范围(第22节)
各角色应得金额后续采用品牌总部转账、再提现,不用余额分账,另行设计;本轮不新增相关接口或执行资金操作。第一阶段分账字段仍一律拒绝。
待定问题与有条件决定
| 编号 / 问题 | 方案 | 状态与条件 | 影响 |
|---|---|---|---|
| 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 |
| 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 |
| 易宝 付款码 / 聚合码订单是否适用关单接口;同步返回缺 `payAmount` 的可信口径;沙箱白名单与配额;通知重试间隔与次数(Q20);对账文件(Q21);退款期限(Q4) | — | 待易宝确认(产品负责人线下问) | P2—P5、验收 |
| 商户结构 品牌总部、门店、教练等的易宝类型 | 门店是品牌总部下的入驻商户(发起方商编 = 平台商编);按商编可配置(第 7.1 节) | 门店:产品负责人已定 11/11;教练、供应链、商户池中的商户:待确认 | P2 配置 |
| 判断顺序(11/11 复审) `Content-Type` 不对回什么 | 统一 401,在验签前判断(第 3.2、4.3 节) | 文档前后统一,属 Q15 范围,异议期同 Q15 | P1 |
| 渠道交易号后 4 位放哪 查单是否加 | 查单不加;只在 facts 和第二跳推送给(第 3.5、12、17 节) | 文档前后统一 | P7 |
| 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 |
- 未在设计稿明确的字段、类型、必填性和响应层级保持未定义,不根据示例反推 schema。
- 返回表未完整展开;这里只结构化设计稿点名的字段,其他上游合法字段仍原样保留。
逐条来源规则与上下文
公共请求规则(全部易宝同款接口)
- POST 用 `application/x-www-form-urlencoded`,GET 用查询串;不接受 JSON:POST 的 `Content-Type` 不是**正好** `application/x-www-form-urlencoded`(JSON、带 `charset` 等)一律回 **401 `UNAUTHENTICATED`**,按第 4.3 节判断顺序第 1 步,在验签之前拒绝、不认领 nonce、不调用渠道(11/11 复审统一为 401,原写的 422 `form_required` 取消)。 - 字段名、大小写照易宝;号码一律按字符串处理,不转整数、不截断、不加前缀。 - 金额对外是元,两位小数文本(如 `303.00`),内部按文本精确解析成整数分,不经过浮点;`0.00`、负数、超过两位小数、科学计数法拒绝。 - 官方 JSON 字符串类型的参数(如 `scene`、`terminalSceneInfo`)保持字符串,按原样转发,不改成嵌套对象。 - 每个接口有**第一阶段允许字段白名单**;白名单外的官方字段一律 422 `VALIDATION_FAILED`,`details.<字段名>=["unsupported_in_phase1"]`,不调用渠道。不认识的非官方字段同样拒绝。 - 同名字段只能出现一次(重复键拒绝);空值 `k=` 和不传是两回事,按各字段规则处理,不互相替代。 - 补齐规则(只有这几项由本服务补,其余必须调用方给):`parentMerchantNo` 不传时按 C05 目录里该收款商户登记的“发起方商编”补(默认例子:门店是品牌总部下的入驻商户,发起方商编是品牌总部的平台商编;标准商户的发起方商编是它自己,见第 7.1 节);`notifyUrl` 发给易宝的一律是本服务入口,调用方传的地址只用于第二跳;`expiredTime` 不传时按第 3.3 / 3.4 节补。显式传入的补齐字段必须和配置一致,否则 403 `SCOPE_DENIED`,不能任意覆盖。
查收款订单 `GET /rest/v1.0/trade/order/query`
**请求**:`parentMerchantNo`(可选,服务补并核对)、`merchantNo`(必填)、`orderId`(必填)。其他参数拒绝。 **行为**(建议): - 只查本应用授权范围内、本服务发起过的订单;不认识的 orderId 回 404 `NOT_FOUND`,不替调用方查别人的单。 - 每次请求在预算内实时查易宝原账户、原商户、原订单;同一订单有进行中的查询时,等它的结果(最多到本次预算),不并发打易宝。 - 查到的结果和本地已确认的事实一致:HTTP 200,返回易宝查单业务结果(官方返回表的全部字段原样原层级原类型,第 6.2 节)。不加本服务自己的字段(包括 `channel_trade_no_last4`,它只在 facts 接口和第二跳推送里给,第 17 节 GPAY02-07);**删掉付款人字段**,清单和规则同第 3.3 节(产品负责人 11/11 12:49 亚利桑那已定)。 - 和本地已确认事实矛盾(如本地已成功、这次查到 FAIL):不返回渠道结果,回 409 `EVIDENCE_CONFLICT`(第 5 节),内部标待核、告警。 - 超时、坏签、缺必要字段:504 / 502(第 5 节),不返回半截结果。
两层鉴权
### 4.1 调用方 → 本服务
- 沿用 `X-SP-Instance`(接入应用 `app_ref`)、`X-SP-Timestamp`(±300 秒)、`X-SP-Nonce`(同应用 600 秒内不可重用,#15 原子认领、到期第 600 秒仍拒绝、第 601 秒可用新签名重新使用)、`X-SP-Signature`(HMAC-SHA256,按应用取密钥,支持轮换过渡)。
- 新增 `X-SP-Sign-Version`:`2` 表示本节的新签名;不带该头即旧版 v1(给旧 POST 和第 12 节内部接口用;旧 POST 下线时 v1 不能一起下线,除非内部接口也已换签名)。
- nonce 只管防重放;业务幂等由 orderId / refundRequestId 加内容摘要承担,两者分开。
### 4.2 旧接口(v1)在并行期的处理(已定,P1 落地)
- `/api/v1/payments/auth-code`、`/api/v1/payments/query` 只认签过名的 JSON body。请求只要带了 query 串,在边界层直接 422 `VALIDATION_FAILED`,`error.details.query=["query_not_allowed"]`,不进入业务、不调通道(Lihao 已确认格式)。
- 两个 FormRequest 覆盖 `validationData()`,只返回 JSON 内容;`PaymentCollections` 只从验证后的 JSON 取 `biz_no` 等字段。
- v1 待签串不变:`method\npath\nsha256(body)\ntimestamp\nnonce`。
### 4.3 新版签名 v2(Q15 已定(Lihao 默认方案,异议期至 11/12 04:50 亚利桑那),P1 落地,上线阻断)
待签串(各行以 `\n` 连接,末尾无换行):
```
SP-HMAC-SHA256-2
<HTTP 方法,大写>
<路径,原样,不做解码>
<规范查询串,见下>
<Content-Type 原值;GET 为空行>
<请求体原始字节的 SHA-256 小写十六进制;GET 为空串的摘要>
<X-SP-Timestamp>
<X-SP-Nonce>
```
规范查询串规则:**服务端不自己重排再验签,而是要求调用方发来的查询串本身就是规范形式**,否则直接拒绝。这样“签的”和“业务读到的”一定是同一串字节。
1. 按 `&` 分成若干对,每一对必须含一个 `=`;空串查询串表示没有参数。
2. 键、值按 UTF-8 编码,只允许未保留字符 `A-Z a-z 0-9 - . _ ~` 原样出现,其余字节一律 `%XX`(十六进制大写);`+` 不允许(空格只能是 `%20`);小写十六进制、对未保留字符的多余编码、非法 UTF-8 都拒绝。
3. 按键的编码后字节升序排列;键重复拒绝。
4. `k=`(空值)和不传 `k` 是两种不同请求,签名不同,业务按各字段规则处理。
5. 服务端解析业务参数时只解析这一串,不用框架的 `$request->query()` / `all()` 合并结果。
POST form 的请求体:
1. 摘要覆盖原始字节,签名不要求排序。
2. 业务读取用本服务自己的严格解析器(同上第 1、2、4 条:每对一个 `=`、编码规范、`+` 拒绝、重复键拒绝),不用框架合并 query 和 body;POST 同时带 query 串直接拒绝。
3. `Content-Type` 必须**正好**是 `application/x-www-form-urlencoded`,不带 `charset` 等参数,否则 401(Q15 已定(Lihao 默认方案,异议期至 11/12 04:50 亚利桑那)),且签进待签串。第 3.2 节同此,不再有 422 `form_required`。
**判断顺序**(POST 和 GET 共用,前一步不过就停,后面不做):
1. POST 的 `Content-Type` 是否正好是 `application/x-www-form-urlencoded` → 否则 401,`invalid_content_type`;POST 是否带 query 串 → 否则 401,`query_not_allowed`。这一步不验签、不认领 nonce。
2. 鉴权头齐全 → 否则 401,`missing_auth_header`;时间戳在 ±300 秒内 → 否则 401,`timestamp_out_of_window`。
3. 规范性:严格解析(每对一个 `=`、编码规范、`+` 拒绝、重复键拒绝)→ 否则 401,`non_canonical`。
4. 验签 → 否则 401,`invalid_signature`。
5. 认领 nonce(600 秒窗口)→ 重用 401,`nonce_reused`;nonce 表抢锁失败 401,`nonce_unavailable`。
6. 授权范围(`merchantNo` 等是否属于本应用)→ 403 `SCOPE_DENIED`。
7. 字段白名单和取值校验 → 422 `VALIDATION_FAILED`;之后才进业务、调渠道。
**401 的机器可读原因**(Lihao 11/11 要求,POS 据此分清表单配置问题和签名问题):返回 `{"error":{"code":"UNAUTHENTICATED","message":"…","details":{"reason":"<原因>"}}}`,`reason` 取上面 1—5 步的值之一:`invalid_content_type`、`query_not_allowed`、`missing_auth_header`、`timestamp_out_of_window`、`non_canonical`、`invalid_signature`、`nonce_reused`,另加下面归并规则里的 `nonce_unavailable`。日志第①段 `auth_result` 用同一套取值(第 13.1 节)。`reason` 只说哪一步没过,不回显期望的签名或待签串。归并规则:鉴权头缺失、重复、格式不对(时间戳不是数字、nonce 长度不对等),以及新接口上 `X-SP-Sign-Version` 缺失或不是 `2`,都算 `missing_auth_header`;应用标识不认识或已停用算 `invalid_signature`(不暴露应用是否存在);nonce 表抢锁失败(第 5 节保留的那种 401)也回 401,但不算重放,`reason` 用 `nonce_unavailable`(第八个值,日志同名),调用方可以换新 nonce 重签再发。401 响应带 `WWW-Authenticate: SP-Sign version="2"` 头。
验收:JSON 体+正确签名、`charset=utf-8`+正确签名,都回 401 `reason=invalid_content_type` 且 nonce 未被占用(同一 nonce 改对 `Content-Type` 重签后能正常通过);签名错一位回 401 `reason=invalid_signature`。
不规范、重复键、签名不符、时间窗外、nonce 重用:401 `UNAUTHENTICATED`(带上面的 `details.reason`),不进业务、不调通道。参数值本身不合法(如金额格式错):通过鉴权后 422。
**调用方怎么生成请求体**(Lihao 11/11):调用方先按上面第 2 条(RFC 3986,空格写 `%20`,十六进制大写)自己生成**一次**表单原始字节,对这份字节算摘要和签名,再把这份字节原样作为请求体发送,`Content-Type` 头手工设成正好 `application/x-www-form-urlencoded`。不要把参数数组交给 HTTP 客户端的默认表单编码(Laravel HTTP / Guzzle 的 `asForm()` / `form_params` 会把空格写成 `+`、可能重排),否则凡是带空格的值都会 401 `non_canonical`。
固定向量:P1 在仓库里放至少 11 组 v2 向量,POS 侧用同一组向量自测:GET 正常、GET 空值、GET 多参数排序、POST form、POST 中文值、带 query 的 POST 被拒(`query_not_allowed`);新增 **POST 含空格和中文**(同一输入,固定请求体原始字节、摘要和签名结果)、**同一输入空格写成 `+`** 被拒(`non_canonical`)、**`Content-Type` 为 JSON** 被拒、**`Content-Type` 带 `charset=utf-8`** 被拒(两组都是 `invalid_content_type`,nonce 未被占用)、**签名错一位**被拒(`invalid_signature`)。(归并规则里的 `missing_auth_header` 格式错误、`nonce_unavailable` 不放固定向量,在 P1 的测试里覆盖。)
### 4.4 本服务 → 易宝
- YOP-RSA2048-SHA256,沿用 `RsaProtocol`、#16 的官方向量(出站签名、应答 `x-yop-sign` 验签、通知数字信封)。新增接口(pay-link、refund、refund/query)在 P3/P4 补对应向量。
- 签名对象是**实际发给易宝的请求**(补齐商编和本服务 notifyUrl 之后),不转发调用方签名冒充 YOP 签名。
- 易宝 AppKey、商户私钥、平台公钥只在服务器 `.env` / 密钥文件;调用方拿不到,库里不存明文,日志不出现。SM2 配置在未验证前继续拒绝。本服务自己的错误(安全例外)
易宝同款接口上,凡不是“验签通过的易宝结果”,都用本服务错误格式,HTTP 状态码区分,**正文里没有易宝的 `code` 字段**,调用方不会把它当成易宝返回:
```json
{"error":{"code":"CHANNEL_TIMEOUT","message":"…","details":{}}}
```
| HTTP | error.code | 场景 | POS 应怎么做 |
| --- | --- | --- | --- |
| 401 | `UNAUTHENTICATED` | `Content-Type` 不正好是 form(含 JSON)、签名、时间窗、nonce、规范化不通过(判断顺序和 `details.reason` 取值见第 4.3 节) | 修请求;`nonce_unavailable` 换新 nonce 重签再发;不算发生过扣款 |
| 403 | `SCOPE_DENIED` | 应用无权操作该门店 / 商户 / 订单;显式商编与配置不符 | 不重试 |
| 404 | `NOT_FOUND` | 查单、关单、退款的 orderId 不是本应用发起的 | 不重试 |
| 409 | `IDEMPOTENCY_CONFLICT` | 同 orderId 或 refundRequestId 内容不同 | 不换号自动重发 |
| 409 | `PAYMENT_IN_PROGRESS` | 同账单已有进行中的收款或有效二维码 | 先查原单 / 关单 |
| 409 | `PAYMENT_PROTECTED`(新,Q14/Q18 已定) | 已付保护拦截了新扣款(前代已成功或可信已付提示) | 查原单、走内部待处理接口,不再扣 |
| 409 | `EVIDENCE_CONFLICT`(新,Q14/Q18 已定) | 查单结果和已确认事实矛盾,已标待核 | 不按这次结果改账单,等人工 |
| 409 | `REFUND_IN_PROGRESS`(新,Q14/Q18 已定) | 同一退款请求号正在派发 | 稍后查退款,不换号 |
| 409 | `REFUND_AMOUNT_EXCEEDED`(新,Q14/Q18 已定) | 退款金额超过可退额度(含处理中、结果不明的占额) | 不重试,先查已有退款 |
| 422 | `VALIDATION_FAILED` | 字段不合法、第一阶段不支持(`unsupported_in_phase1`)、旧 POST 带 query(`query_not_allowed`) | 修请求 |
| 422 | `MERCHANT_NOT_REGISTERED` | 商户号未登记或不可收款 | 不重试 |
| 502 | `CHANNEL_EVIDENCE_INVALID`(新,Q14/Q18 已定) | 易宝有响应但坏签、身份不符、缺必要字段或金额不一致;原单保留待核 | **不自动再扣、不换 orderId**;查原单 |
| 503 | `CHANNEL_NOT_CONFIGURED` / `SERVICE_UNAVAILABLE` | 配置未装配(C05/C06)、本服务依赖不可用 | 稍后重试同一请求 |
| 504 | `CHANNEL_TIMEOUT`(新,Q14/Q18 已定) | 渠道调用超时或预算耗尽;扣款类已可能发出 | **不自动再扣、不换 orderId**;用同一 orderId 查原单 |
- 新错误码名字和 HTTP 状态按本表(Q14、Q18 已定(Lihao 默认方案,异议期至 11/12 04:50 亚利桑那));验收用例 PAY-04、PAY-09-B1 等处在异议期结束后回填。
- 鉴权未通过的请求不认领 nonce、不写业务数据;通过鉴权后发生的错误都写第①段日志。
- 现有 nonce 锁处理不变:MySQL 1213 / 40001 最多重试 3 次,仍冲突回 401;1205 直接 401。返回内容、payAmount 与状态
### 6.1 原则 1. 只返回**这一次**验签通过、身份一致的渠道结果;不拿内部 `PaymentResource` 拼成易宝格式;不把查询结果冒充成先前付款码的原始响应;不把旧 orderId 的成功冒充新 orderId 的成功。 2. 上游给了的合法字段原样、原类型、原层级保留(付款人字段除外,见第 3.3 节);上游没给的不补默认值。 3. 只返回易宝**业务结果对象**,不返回完整 YOP 网关响应(Q1 已定);不再声称原 `x-yop-sign` 能验它;第一阶段不加本服务自己的响应签名(Q2 已定)。两条均(Lihao 默认方案,异议期至 11/12 04:50 亚利桑那)。 ### 6.2 payAmount(01:54 第 3 条) - 付款码同步返回官方没有 `payAmount`(只有 `orderAmount`、`realPayAmount`),**不补**。 - POS 认款以“查单返回里可信的 `payAmount`”为准;查单返回没有可信 `payAmount` 时,本服务回 502 `CHANNEL_EVIDENCE_INVALID`,原单待核,不伪造。 - 禁止:用 `orderAmount` 补 `payAmount`;把 `realPayAmount` 改名当 `payAmount`;用内部 `paid_amount_fen` 反填并声称来自渠道;填 0、null、空串凑必填;负通知缺金额时推断渠道返回零。 - 内部改造:`YeepayClient::evidence` 现在成功时金额取 `orderAmount`,P2 改为成功必须有可信 `payAmount`(通知必填;查单有则核对),金额来源写入事件(`amount_source`)。 - 第一阶段范围内要求 `payAmount = orderAmount`;用户手续费使 `payAmount > orderAmount`、营销使 `realPayAmount` 不同的情况,第一阶段一律按金额不符隔离待核,不宣称支持。 ### 6.3 状态分层(01:54 第 4 条) | 内部事实 | 对外 | | --- | --- | | 渠道可信 SUCCESS,身份和金额完整 | 返回渠道原结果(`status=SUCCESS`) | | UNKNOWN(超时、坏签、未列码、预算耗尽) | 504 或 502,不映射成任何易宝 status | | terminal_conflict、existence_conflict、identity_mismatch | 查单时 409 `EVIDENCE_CONFLICT`;内部待处理接口可见 | | late_success(晚到的可信成功) | 查原单返回真实成功;“晚到”这一事实只在内部待处理接口里给 | | OPR18012 已付提示、金额未核实 | 阻止再扣款(409 `PAYMENT_PROTECTED`),不生成成功金额 | | unpaid_resolved(到期仍不存在,按未支付了结) | 查单如实返回渠道结果(`OPR12002` 订单不存在原样返回);内部记了结事件 | 已确认成功不会被随后的负结果抹掉;矛盾保留审计、标待核、告警。
订单号与账单关联(01:54 第 5 条)
- orderId 由 POS 生成,格式 `<bill_no>_<seq>`:`bill_no` 是 POS 的 18 位账单号(`100000000000000000—999999999999999999`),`seq` 是正整数,1—6 位、不补零(Q4 已定(Lihao 默认方案,异议期至 11/12 04:50 亚利桑那))。本服务按正则 `^([1-9][0-9]{17})_([1-9][0-9]{0,5})$` 校验并解析出 `bill_no`(账单号首位 1—9,和现有 `PaymentOrderNumbers` 一致)。
- 账单关联 subject = 应用 + 品牌 + 门店 + `bill_no`;品牌、门店由 `merchantNo` 经 C05 目录唯一映射,并核对应用授权。同账单锁、进行中保护、前代已付保护、晚到成功都按这个 subject 生效。不靠 nonce、付款码或 memo 推断同一账单。
- 序号由 POS 分配,本服务不重排、不补号;只保证同一商户下 orderId 唯一(现有 `merchant_order_id` 唯一索引)。同一账单出现跳号允许;同号不同内容 409。
- 旧接口的服务端配号(`payment_order_sequences`)只给旧接口用,旧订单编号不改、不迁移。并行期**同一张账单只能走一种接口**,否则两边分配的序号可能撞号(唯一索引会挡住,但会表现为 409)——所以并行期**按门店整体切换**:一家门店一旦切到新接口,该门店所有账单都走新接口(Q4 已定(Lihao 默认方案,异议期至 11/12 04:50 亚利桑那))。
- `biz_no`(SaaS 单号)和 `order_kind` 不在易宝字段里:第一阶段直收不需要它们参与资金计算;`biz_no` 用于账单展示和对账,由内部账单查询接口按 `bill_no` 关联,不塞进 memo(Q10 已定(Lihao 默认方案,异议期至 11/12 04:50 亚利桑那))。
### 7.1 商户结构(产品负责人 11/11 确认)
| 角色 | 是谁 | 易宝类型 | 状态 |
| --- | --- | --- | --- |
| 服务商 | 西安禾斗 | SaaS 服务商,本身不收单 | 已确认 |
| 平台商 | 品牌总部 | 服务商接入的平台商(`PLATFORM_MERCHANT`) | 已确认 |
| 入驻商户 | 品牌门店的收款账户 | 入驻商户(`SETTLED_MERCHANT`),上级是品牌总部 | 已确认 |
| 待确认 | 教练、供应链、商户池中的商户 | 未确认,**不默认成标准商户,也不默认成入驻商户** | 待确认 |
- 本服务用服务商的应用和密钥,一套服务对多个品牌;“接入应用 → 品牌 → 门店 → 商编”的授权核对照旧。
- 商编填法按易宝《产品决策》第一节和付款码、聚合码在线文档:平台商代下属入驻商户收款时,`parentMerchantNo` 是平台商编、`merchantNo` 是收款子商户;标准商户收款时两者一致,都是本商户编号。
- C05 目录里每个收款商编登记一个“发起方商编”(`parent_merchant_no`),按商编配置、不写死:
- **默认(门店)**:发起方商编 = 品牌总部的平台商编,和 `merchantNo` 不同;关单时对应 `OPR00025`“系统商版父子商编必须不一致”的规则。
- **另一种填法(标准商户)**:发起方商编 = 自己的商编;对应 `OPR00024`“标准版父子商编必须一致”。
- 教练、供应链、商户池中的商户:第一阶段不收款,确认类型后再登记。
- 易宝商户角色(服务商入网接口 `businessRole`)(Claude 11/11 按官方 Skill 和在线文档核对):`ORDINARY_MERCHANT` 标准商户、`PLATFORM_MERCHANT` 平台商(入网时 `parentMerchantNo` 填服务商商编);`SETTLED_MERCHANT` 入驻商户只能挂在特定平台商下(入网时 `parentMerchantNo` 填平台商编);另有 `SHARE_MERCHANT` 分账接收方、`HEAD_CHAIN` / `BRANCH_CHAIN` 连锁总店 / 分店。
- 对账:平台商用平台商编下载的交易日账单包含平台商和下面全部入驻商户的交易;标准商户用自己的商编下载(第 20 节)。查单与后台任务
- `payment:poll` 继续按“前 2 分钟每 5 秒、之后每分钟、30 分钟待核、24 小时停自动查并告警、人工可马上查一次且不恢复自动查”运行,覆盖付款码、聚合码;P4 起覆盖退款。 - 对外 GET 查单是实时查(第 3.5 节);后台查单和对外查单共用同一查询租约,不并发打易宝。 - 查询限速:每个订单同时最多一个在途查询;全局按易宝配额限速(配额待易宝确认)。
待定问题与决定
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、验收 |不在本设计范围
- 分账、归集、资金方案、循环收款池、提现、余额(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.1.3.1payment-service-A3
A3 查收款订单支付设计
查询原收款订单的可信渠道结果,供收银台核实是否到账。
契约状态:设计稿实现状态:设计未实现;基线:内核已有,对外仍是旧 JSON 接口真实接口验收:未经沙箱验收
GET
/rest/v1.0/trade/order/queryDESIGN ONLY · NO LIVE CALLi
设计稿,未实现,未经沙箱验收
字段、规则、错误和有条件决定取自固定设计提交;只作展示,不运行请求或模拟成功。
- 仅静态合成示例;设计未实现、未经沙箱验收;不启用模拟成功,不发送 HTTP。
01接口说明
业务端 / 模块支付服务(易宝同款) / A 易宝同款
请求格式查询串(GET)
鉴权与权限本服务签名 v2(第4.1、4.3节):HMAC-SHA256,签名覆盖规范查询串、原始正文和Content-Type;应用→品牌/门店→商户授权核对。 · 设计展示,禁止网络请求
技术服务归属(元信息)支付服务
调用方 → 本服务目录引用不授予调用权限。
来源业务约束
- 未在设计稿明确的字段、类型、必填性和响应层级保持未定义,不根据示例反推 schema。
- 返回表未完整展开;这里只结构化设计稿点名的字段,其他上游合法字段仍原样保留。
02请求头 5 个字段
| 字段名 | 类型 | 必填 | 说明与约束 | 示例值 |
|---|---|---|---|---|
X-SP-Instance | 未定义 | 必填 | 本服务签名头;v2 逐字节规则见第4节。仅展示占位,不能发请求。 | "SYNTHETIC_ONLY" |
X-SP-Timestamp | 未定义 | 必填 | 本服务签名头;v2 逐字节规则见第4节。仅展示占位,不能发请求。 | "SYNTHETIC_ONLY" |
X-SP-Nonce | 未定义 | 必填 | 本服务签名头;v2 逐字节规则见第4节。仅展示占位,不能发请求。 | "SYNTHETIC_ONLY" |
X-SP-Signature | 未定义 | 必填 | 本服务签名头;v2 逐字节规则见第4节。仅展示占位,不能发请求。 | "SYNTHETIC_ONLY" |
X-SP-Sign-Version | string | 必填 | 本服务签名版本固定为2;本服务签名头;v2 逐字节规则见第4节。仅展示占位,不能发请求。固定值:"2" | "2" |
03请求参数 按来源列示,未明确部分不补造
Query / Path / Cookie 参数
| 字段名 | 类型 | 必填 | 第一阶段处理 | 说明与约束 | 示例值 |
|---|---|---|---|---|---|
parentMerchantNo | string | 可选 | 可选,服务补易宝必填:未明确 | 易宝必填性:未明确;第一阶段处理:可选,服务补。按 C05 补齐并核对 | "SYNTHETIC_ONLY" |
merchantNo | string | 必填 | 必填易宝必填:未明确 | 易宝必填性:未明确;第一阶段处理:必填。授权范围内商户 | "DEMO_MERCHANT" |
orderId | string | 必填 | 必填易宝必填:未明确 | 易宝必填性:未明确;第一阶段处理:必填。本服务发起过的订单;其他参数拒绝 | "100000000000000001_1" |
来源没有可展开的字段定义。完整约束可在「来源与状态」查看。
04响应参数
验签通过、身份一致、内容完整的易宝业务结果;返回前按第3.3节删除付款人字段,其余原样原类型。A3不加channel_trade_no_last4。
| 字段名 | 类型 | 必填 | 说明与约束 | 示例值 |
|---|---|---|---|---|
payAmount | 未定义 | 未明确 | 易宝必填性:未明确;第一阶段处理:上游有则保留。上游给出的合法字段原样原类型保留,不补缺失字段;此处仅列设计稿点名字段,不宣称完整官方 schema。 | null |
orderAmount | 未定义 | 未明确 | 易宝必填性:未明确;第一阶段处理:上游有则保留。上游给出的合法字段原样原类型保留,不补缺失字段;此处仅列设计稿点名字段,不宣称完整官方 schema。 | null |
status | 未定义 | 未明确 | 易宝必填性:未明确;第一阶段处理:上游有则保留。上游给出的合法字段原样原类型保留,不补缺失字段;此处仅列设计稿点名字段,不宣称完整官方 schema。 | null |
05错误码 沿用来源定义
| HTTP 状态 | 来源业务码 | 来源说明 |
|---|---|---|
401 | UNAUTHENTICATED | UNAUTHENTICATED:`Content-Type` 不正好是 form(含 JSON)、签名、时间窗、nonce、规范化不通过(判断顺序和 `details.reason` 取值见第 4.3 节);修请求;`nonce_unavailable` 换新 nonce 重签再发;不算发生过扣款 |
403 | SCOPE_DENIED | 应用无权操作该门店 / 商户 / 订单;显式商编与配置不符;不重试 |
404 | NOT_FOUND | 查单、关单、退款的 orderId 不是本应用发起的;不重试 |
409 | IDEMPOTENCY_CONFLICT | 同 orderId 或 refundRequestId 内容不同;不换号自动重发 |
409 | PAYMENT_IN_PROGRESS | 同账单已有进行中的收款或有效二维码;先查原单 / 关单 |
409 | PAYMENT_PROTECTED | 已付保护拦截了新扣款(前代已成功或可信已付提示);查原单、走内部待处理接口,不再扣 |
409 | EVIDENCE_CONFLICT | 查单结果和已确认事实矛盾,已标待核;不按这次结果改账单,等人工 |
409 | REFUND_IN_PROGRESS | 同一退款请求号正在派发;稍后查退款,不换号 |
409 | REFUND_AMOUNT_EXCEEDED | 退款金额超过可退额度(含处理中、结果不明的占额);不重试,先查已有退款 |
422 | VALIDATION_FAILED | 字段不合法、第一阶段不支持(`unsupported_in_phase1`)、旧 POST 带 query(`query_not_allowed`);修请求 |
422 | MERCHANT_NOT_REGISTERED | 商户号未登记或不可收款;不重试 |
502 | CHANNEL_EVIDENCE_INVALID | 易宝有响应但坏签、身份不符、缺必要字段或金额不一致;原单保留待核;不自动再扣、不换 orderId;查原单 |
503 | CHANNEL_NOT_CONFIGURED | 配置未装配(C05/C06)、本服务依赖不可用;稍后重试同一请求 |
503 | SERVICE_UNAVAILABLE | 配置未装配(C05/C06)、本服务依赖不可用;稍后重试同一请求 |
504 | CHANNEL_TIMEOUT | 渠道调用超时或预算耗尽;扣款类已可能发出;不自动再扣、不换 orderId;用同一 orderId 查原单 |
06来源与状态
契约状态:设计稿实现状态:设计未实现;基线:内核已有,对外仍是旧 JSON 接口真实接口验收:未经沙箱验收
sourceCommit
7d2ae11e91ecd073944f98473ef41a67cd0f6146查看原始契约、引用与状态记录
{
"contract": {
"parameters": [
{
"name": "X-SP-Instance",
"in": "header",
"required": true,
"description": "本服务签名头;v2 逐字节规则见第4节。仅展示占位,不能发请求。",
"schema": {},
"example": "SYNTHETIC_ONLY"
},
{
"name": "X-SP-Timestamp",
"in": "header",
"required": true,
"description": "本服务签名头;v2 逐字节规则见第4节。仅展示占位,不能发请求。",
"schema": {},
"example": "SYNTHETIC_ONLY"
},
{
"name": "X-SP-Nonce",
"in": "header",
"required": true,
"description": "本服务签名头;v2 逐字节规则见第4节。仅展示占位,不能发请求。",
"schema": {},
"example": "SYNTHETIC_ONLY"
},
{
"name": "X-SP-Signature",
"in": "header",
"required": true,
"description": "本服务签名头;v2 逐字节规则见第4节。仅展示占位,不能发请求。",
"schema": {},
"example": "SYNTHETIC_ONLY"
},
{
"name": "X-SP-Sign-Version",
"in": "header",
"required": true,
"description": "本服务签名版本固定为2;本服务签名头;v2 逐字节规则见第4节。仅展示占位,不能发请求。",
"schema": {
"const": "2"
},
"example": "2"
},
{
"name": "parentMerchantNo",
"in": "query",
"required": false,
"description": "易宝必填性:未明确;第一阶段处理:可选,服务补。按 C05 补齐并核对",
"schema": {
"type": "string",
"x-payment-required-label": "可选",
"x-payment-processing": "可选,服务补",
"x-supplier-required": "未明确",
"description": "易宝必填性:未明确;第一阶段处理:可选,服务补。按 C05 补齐并核对"
},
"example": "SYNTHETIC_ONLY"
},
{
"name": "merchantNo",
"in": "query",
"required": true,
"description": "易宝必填性:未明确;第一阶段处理:必填。授权范围内商户",
"schema": {
"type": "string",
"x-payment-required-label": "必填",
"x-payment-processing": "必填",
"x-supplier-required": "未明确",
"description": "易宝必填性:未明确;第一阶段处理:必填。授权范围内商户"
},
"example": "DEMO_MERCHANT"
},
{
"name": "orderId",
"in": "query",
"required": true,
"description": "易宝必填性:未明确;第一阶段处理:必填。本服务发起过的订单;其他参数拒绝",
"schema": {
"type": "string",
"x-payment-required-label": "必填",
"x-payment-processing": "必填",
"x-supplier-required": "未明确",
"description": "易宝必填性:未明确;第一阶段处理:必填。本服务发起过的订单;其他参数拒绝"
},
"example": "100000000000000001_1"
}
],
"responses": {
"200": {
"description": "验签通过、身份一致、内容完整的易宝业务结果;返回前按第3.3节删除付款人字段,其余原样原类型。A3不加channel_trade_no_last4。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"payAmount": {
"x-payment-required-label": "未明确",
"x-payment-processing": "上游有则保留",
"x-supplier-required": "未明确",
"description": "易宝必填性:未明确;第一阶段处理:上游有则保留。上游给出的合法字段原样原类型保留,不补缺失字段;此处仅列设计稿点名字段,不宣称完整官方 schema。"
},
"orderAmount": {
"x-payment-required-label": "未明确",
"x-payment-processing": "上游有则保留",
"x-supplier-required": "未明确",
"description": "易宝必填性:未明确;第一阶段处理:上游有则保留。上游给出的合法字段原样原类型保留,不补缺失字段;此处仅列设计稿点名字段,不宣称完整官方 schema。"
},
"status": {
"x-payment-required-label": "未明确",
"x-payment-processing": "上游有则保留",
"x-supplier-required": "未明确",
"description": "易宝必填性:未明确;第一阶段处理:上游有则保留。上游给出的合法字段原样原类型保留,不补缺失字段;此处仅列设计稿点名字段,不宣称完整官方 schema。"
}
},
"required": []
},
"example": {}
}
}
},
"401": {
"description": "UNAUTHENTICATED:`Content-Type` 不正好是 form(含 JSON)、签名、时间窗、nonce、规范化不通过(判断顺序和 `details.reason` 取值见第 4.3 节);修请求;`nonce_unavailable` 换新 nonce 重签再发;不算发生过扣款",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {},
"message": {},
"details": {}
}
}
}
},
"example": {
"error": {
"code": "UNAUTHENTICATED",
"message": "合成安全错误示例",
"details": {}
}
}
}
},
"headers": {
"WWW-Authenticate": {
"description": "SP-Sign version=\"2\"(第4.3节)",
"schema": {
"type": "string"
},
"example": "SP-Sign version=\"2\""
}
}
},
"403": {
"description": "SCOPE_DENIED:应用无权操作该门店 / 商户 / 订单;显式商编与配置不符;不重试",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {},
"message": {},
"details": {}
}
}
}
},
"example": {
"error": {
"code": "SCOPE_DENIED",
"message": "合成安全错误示例",
"details": {}
}
}
}
}
},
"404": {
"description": "NOT_FOUND:查单、关单、退款的 orderId 不是本应用发起的;不重试",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {},
"message": {},
"details": {}
}
}
}
},
"example": {
"error": {
"code": "NOT_FOUND",
"message": "合成安全错误示例",
"details": {}
}
}
}
}
},
"409": {
"description": "IDEMPOTENCY_CONFLICT:同 orderId 或 refundRequestId 内容不同;不换号自动重发;PAYMENT_IN_PROGRESS:同账单已有进行中的收款或有效二维码;先查原单 / 关单;PAYMENT_PROTECTED:已付保护拦截了新扣款(前代已成功或可信已付提示);查原单、走内部待处理接口,不再扣;EVIDENCE_CONFLICT:查单结果和已确认事实矛盾,已标待核;不按这次结果改账单,等人工;REFUND_IN_PROGRESS:同一退款请求号正在派发;稍后查退款,不换号;REFUND_AMOUNT_EXCEEDED:退款金额超过可退额度(含处理中、结果不明的占额);不重试,先查已有退款",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {},
"message": {},
"details": {}
}
}
}
},
"example": {
"error": {
"code": "IDEMPOTENCY_CONFLICT",
"message": "合成安全错误示例",
"details": {}
}
}
}
}
},
"422": {
"description": "VALIDATION_FAILED:字段不合法、第一阶段不支持(`unsupported_in_phase1`)、旧 POST 带 query(`query_not_allowed`);修请求;MERCHANT_NOT_REGISTERED:商户号未登记或不可收款;不重试",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {},
"message": {},
"details": {}
}
}
}
},
"example": {
"error": {
"code": "VALIDATION_FAILED",
"message": "合成安全错误示例",
"details": {}
}
}
}
}
},
"502": {
"description": "CHANNEL_EVIDENCE_INVALID:易宝有响应但坏签、身份不符、缺必要字段或金额不一致;原单保留待核;不自动再扣、不换 orderId;查原单",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {},
"message": {},
"details": {}
}
}
}
},
"example": {
"error": {
"code": "CHANNEL_EVIDENCE_INVALID",
"message": "合成安全错误示例",
"details": {}
}
}
}
}
},
"503": {
"description": "CHANNEL_NOT_CONFIGURED:配置未装配(C05/C06)、本服务依赖不可用;稍后重试同一请求;SERVICE_UNAVAILABLE:配置未装配(C05/C06)、本服务依赖不可用;稍后重试同一请求",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {},
"message": {},
"details": {}
}
}
}
},
"example": {
"error": {
"code": "CHANNEL_NOT_CONFIGURED",
"message": "合成安全错误示例",
"details": {}
}
}
}
}
},
"504": {
"description": "CHANNEL_TIMEOUT:渠道调用超时或预算耗尽;扣款类已可能发出;不自动再扣、不换 orderId;用同一 orderId 查原单",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {},
"message": {},
"details": {}
}
}
}
},
"example": {
"error": {
"code": "CHANNEL_TIMEOUT",
"message": "合成安全错误示例",
"details": {}
}
}
}
}
}
},
"sourceExtensions": {
"x-permission": "设计展示,禁止网络请求",
"x-source-sections": [
"3.2",
"3.5",
"4",
"5",
"6",
"7",
"9",
"19",
"22"
]
}
},
"status": {
"contract": "设计稿",
"implementation": "设计未实现;基线:内核已有,对外仍是旧 JSON 接口",
"realApiAcceptance": "未经沙箱验收"
},
"provenance": {
"sourceCommit": "7d2ae11e91ecd073944f98473ef41a67cd0f6146",
"sourceBlob": "74501663abc0df79dd867f39057b29e7cd1345b3",
"sourceUrl": "https://github.com/SmartPool-Dev/smartpool-payment-service/pull/17",
"paymentService": {
"code": "A3",
"group": "易宝同款业务接口",
"purpose": "查询原收款订单的可信渠道结果,供收银台核实是否到账。",
"direction": "调用方 → 本服务",
"supplier": {
"name": "查单",
"id": "trade-order-query",
"path": "/rest/v1.0/trade/order/query",
"documentId": "1fe6aa427dc941cc8228fe9700a74eab"
},
"phase": "P2",
"baselineStatus": "内核已有,对外仍是旧 JSON 接口",
"differences": [
"调用方使用本服务签名而非 YOP,易宝 SDK 不能零改动直连。",
"易宝回调先到本服务再签名推给调用方,不是字节级透传。",
"安全错误使用本服务 error 外层,不冒充易宝 code;业务结果不加 data/meta。",
"只支持门店直收;不支持的官方字段明确拒绝,未知字段也拒绝。",
"门店已确认是品牌总部下的入驻商户(SETTLED_MERCHANT);默认 parentMerchantNo 为品牌总部的平台商编,与 merchantNo 不同。标准商户同编是另一种按商编配置;教练、供应链、商户池类型仍待确认,第一阶段不收款,不默认任何类型。",
"产品负责人11/11 12:49已定:同步返回删除第3.3节付款人字段,其余易宝字段原样原类型;理由是付款人信息不保留。顶层完整channelTrxId不截短,日志及推送的后4位规则不用于同步返回。"
],
"openQuestions": [
{
"id": "Q1",
"question": "返回业务结果对象还是完整 YOP 网关响应",
"decision": "只返回易宝业务结果对象(第 3.3、6.1 节)",
"status": "Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效",
"impact": "P2"
},
{
"id": "Q2",
"question": "是否加本服务响应签名",
"decision": "第一阶段不加(第 6.1 节)",
"status": "Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效",
"impact": "P2"
},
{
"id": "Q3",
"question": "`merchantNo` 是否必填",
"decision": "必填(第 3.3 节)",
"status": "Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效",
"impact": "P2"
},
{
"id": "Q4",
"question": "并行期怎么切、序号位数",
"decision": "按门店整体切换;序号 1—6 位、不补零(第 7 节)",
"status": "Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效",
"impact": "P2"
},
{
"id": "Q14",
"question": "新错误码名字和 HTTP 状态",
"decision": "按第 5 节",
"status": "Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效",
"impact": "P2 起"
},
{
"id": "Q15",
"question": "签名 v2 逐字节规则",
"decision": "按第 4.3 节;`Content-Type` 只认 `application/x-www-form-urlencoded`,不带 charset",
"status": "Lihao 默认方案,异议期至 11/12 04:50(亚利桑那),到时无异议即生效",
"impact": "P1"
},
{
"id": "易宝",
"question": "付款码 / 聚合码订单是否适用关单接口;同步返回缺 `payAmount` 的可信口径;沙箱白名单与配额;通知重试间隔与次数(Q20);对账文件(Q21);退款期限(Q4)",
"decision": "—",
"status": "待易宝确认(产品负责人线下问)",
"impact": "P2—P5、验收"
},
{
"id": "商户结构",
"question": "品牌总部、门店、教练等的易宝类型",
"decision": "门店是品牌总部下的入驻商户(发起方商编 = 平台商编);按商编可配置(第 7.1 节)",
"status": "门店:产品负责人已定 11/11;教练、供应链、商户池中的商户:待确认",
"impact": "P2 配置"
},
{
"id": "判断顺序(11/11 复审)",
"question": "`Content-Type` 不对回什么",
"decision": "统一 401,在验签前判断(第 3.2、4.3 节)",
"status": "文档前后统一,属 Q15 范围,异议期同 Q15",
"impact": "P1"
},
{
"id": "渠道交易号后 4 位放哪",
"question": "查单是否加",
"decision": "查单不加;只在 facts 和第二跳推送给(第 3.5、12、17 节)",
"status": "文档前后统一",
"impact": "P7"
},
{
"id": "401 原因",
"question": "401 能否分清原因",
"decision": "`details.reason` 八个取值(含 `nonce_unavailable`)、日志同一套、带 `WWW-Authenticate`;调用方自己生成一次表单字节再签名发送;向量 11 组(第 4.3 节)",
"status": "Lihao 11/11 要求;名字按他举例,异议期同 Q15",
"impact": "P1"
},
{
"id": "同步返回里的付款人字段",
"question": "付款码、查单的同步返回按 Q1 原样会带上易宝给的付款人字段(`payerInfo` 等),要不要也去掉",
"decision": "去掉,清单见第 3.3 节,其余字段照旧(第 1 节第 4 处例外)",
"status": "产品负责人已定 11/11 12:49(亚利桑那)",
"impact": "P2"
}
],
"sourceSections": [
{
"id": "3.2",
"title": "公共请求规则(全部易宝同款接口)",
"body": "- POST 用 `application/x-www-form-urlencoded`,GET 用查询串;不接受 JSON:POST 的 `Content-Type` 不是**正好** `application/x-www-form-urlencoded`(JSON、带 `charset` 等)一律回 **401 `UNAUTHENTICATED`**,按第 4.3 节判断顺序第 1 步,在验签之前拒绝、不认领 nonce、不调用渠道(11/11 复审统一为 401,原写的 422 `form_required` 取消)。\n- 字段名、大小写照易宝;号码一律按字符串处理,不转整数、不截断、不加前缀。\n- 金额对外是元,两位小数文本(如 `303.00`),内部按文本精确解析成整数分,不经过浮点;`0.00`、负数、超过两位小数、科学计数法拒绝。\n- 官方 JSON 字符串类型的参数(如 `scene`、`terminalSceneInfo`)保持字符串,按原样转发,不改成嵌套对象。\n- 每个接口有**第一阶段允许字段白名单**;白名单外的官方字段一律 422 `VALIDATION_FAILED`,`details.<字段名>=[\"unsupported_in_phase1\"]`,不调用渠道。不认识的非官方字段同样拒绝。\n- 同名字段只能出现一次(重复键拒绝);空值 `k=` 和不传是两回事,按各字段规则处理,不互相替代。\n- 补齐规则(只有这几项由本服务补,其余必须调用方给):`parentMerchantNo` 不传时按 C05 目录里该收款商户登记的“发起方商编”补(默认例子:门店是品牌总部下的入驻商户,发起方商编是品牌总部的平台商编;标准商户的发起方商编是它自己,见第 7.1 节);`notifyUrl` 发给易宝的一律是本服务入口,调用方传的地址只用于第二跳;`expiredTime` 不传时按第 3.3 / 3.4 节补。显式传入的补齐字段必须和配置一致,否则 403 `SCOPE_DENIED`,不能任意覆盖。"
},
{
"id": "3.5",
"title": "查收款订单 `GET /rest/v1.0/trade/order/query`",
"body": "**请求**:`parentMerchantNo`(可选,服务补并核对)、`merchantNo`(必填)、`orderId`(必填)。其他参数拒绝。\n\n**行为**(建议):\n- 只查本应用授权范围内、本服务发起过的订单;不认识的 orderId 回 404 `NOT_FOUND`,不替调用方查别人的单。\n- 每次请求在预算内实时查易宝原账户、原商户、原订单;同一订单有进行中的查询时,等它的结果(最多到本次预算),不并发打易宝。\n- 查到的结果和本地已确认的事实一致:HTTP 200,返回易宝查单业务结果(官方返回表的全部字段原样原层级原类型,第 6.2 节)。不加本服务自己的字段(包括 `channel_trade_no_last4`,它只在 facts 接口和第二跳推送里给,第 17 节 GPAY02-07);**删掉付款人字段**,清单和规则同第 3.3 节(产品负责人 11/11 12:49 亚利桑那已定)。\n- 和本地已确认事实矛盾(如本地已成功、这次查到 FAIL):不返回渠道结果,回 409 `EVIDENCE_CONFLICT`(第 5 节),内部标待核、告警。\n- 超时、坏签、缺必要字段:504 / 502(第 5 节),不返回半截结果。"
},
{
"id": "4",
"title": "两层鉴权",
"body": "### 4.1 调用方 → 本服务\n\n- 沿用 `X-SP-Instance`(接入应用 `app_ref`)、`X-SP-Timestamp`(±300 秒)、`X-SP-Nonce`(同应用 600 秒内不可重用,#15 原子认领、到期第 600 秒仍拒绝、第 601 秒可用新签名重新使用)、`X-SP-Signature`(HMAC-SHA256,按应用取密钥,支持轮换过渡)。\n- 新增 `X-SP-Sign-Version`:`2` 表示本节的新签名;不带该头即旧版 v1(给旧 POST 和第 12 节内部接口用;旧 POST 下线时 v1 不能一起下线,除非内部接口也已换签名)。\n- nonce 只管防重放;业务幂等由 orderId / refundRequestId 加内容摘要承担,两者分开。\n\n### 4.2 旧接口(v1)在并行期的处理(已定,P1 落地)\n\n- `/api/v1/payments/auth-code`、`/api/v1/payments/query` 只认签过名的 JSON body。请求只要带了 query 串,在边界层直接 422 `VALIDATION_FAILED`,`error.details.query=[\"query_not_allowed\"]`,不进入业务、不调通道(Lihao 已确认格式)。\n- 两个 FormRequest 覆盖 `validationData()`,只返回 JSON 内容;`PaymentCollections` 只从验证后的 JSON 取 `biz_no` 等字段。\n- v1 待签串不变:`method\\npath\\nsha256(body)\\ntimestamp\\nnonce`。\n\n### 4.3 新版签名 v2(Q15 已定(Lihao 默认方案,异议期至 11/12 04:50 亚利桑那),P1 落地,上线阻断)\n\n待签串(各行以 `\\n` 连接,末尾无换行):\n\n```\nSP-HMAC-SHA256-2\n<HTTP 方法,大写>\n<路径,原样,不做解码>\n<规范查询串,见下>\n<Content-Type 原值;GET 为空行>\n<请求体原始字节的 SHA-256 小写十六进制;GET 为空串的摘要>\n<X-SP-Timestamp>\n<X-SP-Nonce>\n```\n\n规范查询串规则:**服务端不自己重排再验签,而是要求调用方发来的查询串本身就是规范形式**,否则直接拒绝。这样“签的”和“业务读到的”一定是同一串字节。\n\n1. 按 `&` 分成若干对,每一对必须含一个 `=`;空串查询串表示没有参数。\n2. 键、值按 UTF-8 编码,只允许未保留字符 `A-Z a-z 0-9 - . _ ~` 原样出现,其余字节一律 `%XX`(十六进制大写);`+` 不允许(空格只能是 `%20`);小写十六进制、对未保留字符的多余编码、非法 UTF-8 都拒绝。\n3. 按键的编码后字节升序排列;键重复拒绝。\n4. `k=`(空值)和不传 `k` 是两种不同请求,签名不同,业务按各字段规则处理。\n5. 服务端解析业务参数时只解析这一串,不用框架的 `$request->query()` / `all()` 合并结果。\n\nPOST form 的请求体:\n\n1. 摘要覆盖原始字节,签名不要求排序。\n2. 业务读取用本服务自己的严格解析器(同上第 1、2、4 条:每对一个 `=`、编码规范、`+` 拒绝、重复键拒绝),不用框架合并 query 和 body;POST 同时带 query 串直接拒绝。\n3. `Content-Type` 必须**正好**是 `application/x-www-form-urlencoded`,不带 `charset` 等参数,否则 401(Q15 已定(Lihao 默认方案,异议期至 11/12 04:50 亚利桑那)),且签进待签串。第 3.2 节同此,不再有 422 `form_required`。\n\n**判断顺序**(POST 和 GET 共用,前一步不过就停,后面不做):\n\n1. POST 的 `Content-Type` 是否正好是 `application/x-www-form-urlencoded` → 否则 401,`invalid_content_type`;POST 是否带 query 串 → 否则 401,`query_not_allowed`。这一步不验签、不认领 nonce。\n2. 鉴权头齐全 → 否则 401,`missing_auth_header`;时间戳在 ±300 秒内 → 否则 401,`timestamp_out_of_window`。\n3. 规范性:严格解析(每对一个 `=`、编码规范、`+` 拒绝、重复键拒绝)→ 否则 401,`non_canonical`。\n4. 验签 → 否则 401,`invalid_signature`。\n5. 认领 nonce(600 秒窗口)→ 重用 401,`nonce_reused`;nonce 表抢锁失败 401,`nonce_unavailable`。\n6. 授权范围(`merchantNo` 等是否属于本应用)→ 403 `SCOPE_DENIED`。\n7. 字段白名单和取值校验 → 422 `VALIDATION_FAILED`;之后才进业务、调渠道。\n\n**401 的机器可读原因**(Lihao 11/11 要求,POS 据此分清表单配置问题和签名问题):返回 `{\"error\":{\"code\":\"UNAUTHENTICATED\",\"message\":\"…\",\"details\":{\"reason\":\"<原因>\"}}}`,`reason` 取上面 1—5 步的值之一:`invalid_content_type`、`query_not_allowed`、`missing_auth_header`、`timestamp_out_of_window`、`non_canonical`、`invalid_signature`、`nonce_reused`,另加下面归并规则里的 `nonce_unavailable`。日志第①段 `auth_result` 用同一套取值(第 13.1 节)。`reason` 只说哪一步没过,不回显期望的签名或待签串。归并规则:鉴权头缺失、重复、格式不对(时间戳不是数字、nonce 长度不对等),以及新接口上 `X-SP-Sign-Version` 缺失或不是 `2`,都算 `missing_auth_header`;应用标识不认识或已停用算 `invalid_signature`(不暴露应用是否存在);nonce 表抢锁失败(第 5 节保留的那种 401)也回 401,但不算重放,`reason` 用 `nonce_unavailable`(第八个值,日志同名),调用方可以换新 nonce 重签再发。401 响应带 `WWW-Authenticate: SP-Sign version=\"2\"` 头。\n\n验收:JSON 体+正确签名、`charset=utf-8`+正确签名,都回 401 `reason=invalid_content_type` 且 nonce 未被占用(同一 nonce 改对 `Content-Type` 重签后能正常通过);签名错一位回 401 `reason=invalid_signature`。\n\n不规范、重复键、签名不符、时间窗外、nonce 重用:401 `UNAUTHENTICATED`(带上面的 `details.reason`),不进业务、不调通道。参数值本身不合法(如金额格式错):通过鉴权后 422。\n\n**调用方怎么生成请求体**(Lihao 11/11):调用方先按上面第 2 条(RFC 3986,空格写 `%20`,十六进制大写)自己生成**一次**表单原始字节,对这份字节算摘要和签名,再把这份字节原样作为请求体发送,`Content-Type` 头手工设成正好 `application/x-www-form-urlencoded`。不要把参数数组交给 HTTP 客户端的默认表单编码(Laravel HTTP / Guzzle 的 `asForm()` / `form_params` 会把空格写成 `+`、可能重排),否则凡是带空格的值都会 401 `non_canonical`。\n\n固定向量:P1 在仓库里放至少 11 组 v2 向量,POS 侧用同一组向量自测:GET 正常、GET 空值、GET 多参数排序、POST form、POST 中文值、带 query 的 POST 被拒(`query_not_allowed`);新增 **POST 含空格和中文**(同一输入,固定请求体原始字节、摘要和签名结果)、**同一输入空格写成 `+`** 被拒(`non_canonical`)、**`Content-Type` 为 JSON** 被拒、**`Content-Type` 带 `charset=utf-8`** 被拒(两组都是 `invalid_content_type`,nonce 未被占用)、**签名错一位**被拒(`invalid_signature`)。(归并规则里的 `missing_auth_header` 格式错误、`nonce_unavailable` 不放固定向量,在 P1 的测试里覆盖。)\n\n### 4.4 本服务 → 易宝\n\n- YOP-RSA2048-SHA256,沿用 `RsaProtocol`、#16 的官方向量(出站签名、应答 `x-yop-sign` 验签、通知数字信封)。新增接口(pay-link、refund、refund/query)在 P3/P4 补对应向量。\n- 签名对象是**实际发给易宝的请求**(补齐商编和本服务 notifyUrl 之后),不转发调用方签名冒充 YOP 签名。\n- 易宝 AppKey、商户私钥、平台公钥只在服务器 `.env` / 密钥文件;调用方拿不到,库里不存明文,日志不出现。SM2 配置在未验证前继续拒绝。"
},
{
"id": "5",
"title": "本服务自己的错误(安全例外)",
"body": "易宝同款接口上,凡不是“验签通过的易宝结果”,都用本服务错误格式,HTTP 状态码区分,**正文里没有易宝的 `code` 字段**,调用方不会把它当成易宝返回:\n\n```json\n{\"error\":{\"code\":\"CHANNEL_TIMEOUT\",\"message\":\"…\",\"details\":{}}}\n```\n\n| HTTP | error.code | 场景 | POS 应怎么做 |\n| --- | --- | --- | --- |\n| 401 | `UNAUTHENTICATED` | `Content-Type` 不正好是 form(含 JSON)、签名、时间窗、nonce、规范化不通过(判断顺序和 `details.reason` 取值见第 4.3 节) | 修请求;`nonce_unavailable` 换新 nonce 重签再发;不算发生过扣款 |\n| 403 | `SCOPE_DENIED` | 应用无权操作该门店 / 商户 / 订单;显式商编与配置不符 | 不重试 |\n| 404 | `NOT_FOUND` | 查单、关单、退款的 orderId 不是本应用发起的 | 不重试 |\n| 409 | `IDEMPOTENCY_CONFLICT` | 同 orderId 或 refundRequestId 内容不同 | 不换号自动重发 |\n| 409 | `PAYMENT_IN_PROGRESS` | 同账单已有进行中的收款或有效二维码 | 先查原单 / 关单 |\n| 409 | `PAYMENT_PROTECTED`(新,Q14/Q18 已定) | 已付保护拦截了新扣款(前代已成功或可信已付提示) | 查原单、走内部待处理接口,不再扣 |\n| 409 | `EVIDENCE_CONFLICT`(新,Q14/Q18 已定) | 查单结果和已确认事实矛盾,已标待核 | 不按这次结果改账单,等人工 |\n| 409 | `REFUND_IN_PROGRESS`(新,Q14/Q18 已定) | 同一退款请求号正在派发 | 稍后查退款,不换号 |\n| 409 | `REFUND_AMOUNT_EXCEEDED`(新,Q14/Q18 已定) | 退款金额超过可退额度(含处理中、结果不明的占额) | 不重试,先查已有退款 |\n| 422 | `VALIDATION_FAILED` | 字段不合法、第一阶段不支持(`unsupported_in_phase1`)、旧 POST 带 query(`query_not_allowed`) | 修请求 |\n| 422 | `MERCHANT_NOT_REGISTERED` | 商户号未登记或不可收款 | 不重试 |\n| 502 | `CHANNEL_EVIDENCE_INVALID`(新,Q14/Q18 已定) | 易宝有响应但坏签、身份不符、缺必要字段或金额不一致;原单保留待核 | **不自动再扣、不换 orderId**;查原单 |\n| 503 | `CHANNEL_NOT_CONFIGURED` / `SERVICE_UNAVAILABLE` | 配置未装配(C05/C06)、本服务依赖不可用 | 稍后重试同一请求 |\n| 504 | `CHANNEL_TIMEOUT`(新,Q14/Q18 已定) | 渠道调用超时或预算耗尽;扣款类已可能发出 | **不自动再扣、不换 orderId**;用同一 orderId 查原单 |\n\n- 新错误码名字和 HTTP 状态按本表(Q14、Q18 已定(Lihao 默认方案,异议期至 11/12 04:50 亚利桑那));验收用例 PAY-04、PAY-09-B1 等处在异议期结束后回填。\n- 鉴权未通过的请求不认领 nonce、不写业务数据;通过鉴权后发生的错误都写第①段日志。\n- 现有 nonce 锁处理不变:MySQL 1213 / 40001 最多重试 3 次,仍冲突回 401;1205 直接 401。"
},
{
"id": "6",
"title": "返回内容、payAmount 与状态",
"body": "### 6.1 原则\n\n1. 只返回**这一次**验签通过、身份一致的渠道结果;不拿内部 `PaymentResource` 拼成易宝格式;不把查询结果冒充成先前付款码的原始响应;不把旧 orderId 的成功冒充新 orderId 的成功。\n2. 上游给了的合法字段原样、原类型、原层级保留(付款人字段除外,见第 3.3 节);上游没给的不补默认值。\n3. 只返回易宝**业务结果对象**,不返回完整 YOP 网关响应(Q1 已定);不再声称原 `x-yop-sign` 能验它;第一阶段不加本服务自己的响应签名(Q2 已定)。两条均(Lihao 默认方案,异议期至 11/12 04:50 亚利桑那)。\n\n### 6.2 payAmount(01:54 第 3 条)\n\n- 付款码同步返回官方没有 `payAmount`(只有 `orderAmount`、`realPayAmount`),**不补**。\n- POS 认款以“查单返回里可信的 `payAmount`”为准;查单返回没有可信 `payAmount` 时,本服务回 502 `CHANNEL_EVIDENCE_INVALID`,原单待核,不伪造。\n- 禁止:用 `orderAmount` 补 `payAmount`;把 `realPayAmount` 改名当 `payAmount`;用内部 `paid_amount_fen` 反填并声称来自渠道;填 0、null、空串凑必填;负通知缺金额时推断渠道返回零。\n- 内部改造:`YeepayClient::evidence` 现在成功时金额取 `orderAmount`,P2 改为成功必须有可信 `payAmount`(通知必填;查单有则核对),金额来源写入事件(`amount_source`)。\n- 第一阶段范围内要求 `payAmount = orderAmount`;用户手续费使 `payAmount > orderAmount`、营销使 `realPayAmount` 不同的情况,第一阶段一律按金额不符隔离待核,不宣称支持。\n\n### 6.3 状态分层(01:54 第 4 条)\n\n| 内部事实 | 对外 |\n| --- | --- |\n| 渠道可信 SUCCESS,身份和金额完整 | 返回渠道原结果(`status=SUCCESS`) |\n| UNKNOWN(超时、坏签、未列码、预算耗尽) | 504 或 502,不映射成任何易宝 status |\n| terminal_conflict、existence_conflict、identity_mismatch | 查单时 409 `EVIDENCE_CONFLICT`;内部待处理接口可见 |\n| late_success(晚到的可信成功) | 查原单返回真实成功;“晚到”这一事实只在内部待处理接口里给 |\n| OPR18012 已付提示、金额未核实 | 阻止再扣款(409 `PAYMENT_PROTECTED`),不生成成功金额 |\n| unpaid_resolved(到期仍不存在,按未支付了结) | 查单如实返回渠道结果(`OPR12002` 订单不存在原样返回);内部记了结事件 |\n\n已确认成功不会被随后的负结果抹掉;矛盾保留审计、标待核、告警。"
},
{
"id": "7",
"title": "订单号与账单关联(01:54 第 5 条)",
"body": "- orderId 由 POS 生成,格式 `<bill_no>_<seq>`:`bill_no` 是 POS 的 18 位账单号(`100000000000000000—999999999999999999`),`seq` 是正整数,1—6 位、不补零(Q4 已定(Lihao 默认方案,异议期至 11/12 04:50 亚利桑那))。本服务按正则 `^([1-9][0-9]{17})_([1-9][0-9]{0,5})$` 校验并解析出 `bill_no`(账单号首位 1—9,和现有 `PaymentOrderNumbers` 一致)。\n- 账单关联 subject = 应用 + 品牌 + 门店 + `bill_no`;品牌、门店由 `merchantNo` 经 C05 目录唯一映射,并核对应用授权。同账单锁、进行中保护、前代已付保护、晚到成功都按这个 subject 生效。不靠 nonce、付款码或 memo 推断同一账单。\n- 序号由 POS 分配,本服务不重排、不补号;只保证同一商户下 orderId 唯一(现有 `merchant_order_id` 唯一索引)。同一账单出现跳号允许;同号不同内容 409。\n- 旧接口的服务端配号(`payment_order_sequences`)只给旧接口用,旧订单编号不改、不迁移。并行期**同一张账单只能走一种接口**,否则两边分配的序号可能撞号(唯一索引会挡住,但会表现为 409)——所以并行期**按门店整体切换**:一家门店一旦切到新接口,该门店所有账单都走新接口(Q4 已定(Lihao 默认方案,异议期至 11/12 04:50 亚利桑那))。\n- `biz_no`(SaaS 单号)和 `order_kind` 不在易宝字段里:第一阶段直收不需要它们参与资金计算;`biz_no` 用于账单展示和对账,由内部账单查询接口按 `bill_no` 关联,不塞进 memo(Q10 已定(Lihao 默认方案,异议期至 11/12 04:50 亚利桑那))。\n\n### 7.1 商户结构(产品负责人 11/11 确认)\n\n| 角色 | 是谁 | 易宝类型 | 状态 |\n| --- | --- | --- | --- |\n| 服务商 | 西安禾斗 | SaaS 服务商,本身不收单 | 已确认 |\n| 平台商 | 品牌总部 | 服务商接入的平台商(`PLATFORM_MERCHANT`) | 已确认 |\n| 入驻商户 | 品牌门店的收款账户 | 入驻商户(`SETTLED_MERCHANT`),上级是品牌总部 | 已确认 |\n| 待确认 | 教练、供应链、商户池中的商户 | 未确认,**不默认成标准商户,也不默认成入驻商户** | 待确认 |\n\n- 本服务用服务商的应用和密钥,一套服务对多个品牌;“接入应用 → 品牌 → 门店 → 商编”的授权核对照旧。\n- 商编填法按易宝《产品决策》第一节和付款码、聚合码在线文档:平台商代下属入驻商户收款时,`parentMerchantNo` 是平台商编、`merchantNo` 是收款子商户;标准商户收款时两者一致,都是本商户编号。\n- C05 目录里每个收款商编登记一个“发起方商编”(`parent_merchant_no`),按商编配置、不写死:\n - **默认(门店)**:发起方商编 = 品牌总部的平台商编,和 `merchantNo` 不同;关单时对应 `OPR00025`“系统商版父子商编必须不一致”的规则。\n - **另一种填法(标准商户)**:发起方商编 = 自己的商编;对应 `OPR00024`“标准版父子商编必须一致”。\n - 教练、供应链、商户池中的商户:第一阶段不收款,确认类型后再登记。\n- 易宝商户角色(服务商入网接口 `businessRole`)(Claude 11/11 按官方 Skill 和在线文档核对):`ORDINARY_MERCHANT` 标准商户、`PLATFORM_MERCHANT` 平台商(入网时 `parentMerchantNo` 填服务商商编);`SETTLED_MERCHANT` 入驻商户只能挂在特定平台商下(入网时 `parentMerchantNo` 填平台商编);另有 `SHARE_MERCHANT` 分账接收方、`HEAD_CHAIN` / `BRANCH_CHAIN` 连锁总店 / 分店。\n- 对账:平台商用平台商编下载的交易日账单包含平台商和下面全部入驻商户的交易;标准商户用自己的商编下载(第 20 节)。"
},
{
"id": "9",
"title": "查单与后台任务",
"body": "- `payment:poll` 继续按“前 2 分钟每 5 秒、之后每分钟、30 分钟待核、24 小时停自动查并告警、人工可马上查一次且不恢复自动查”运行,覆盖付款码、聚合码;P4 起覆盖退款。\n- 对外 GET 查单是实时查(第 3.5 节);后台查单和对外查单共用同一查询租约,不并发打易宝。\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": "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": [
{
"name": "parentMerchantNo",
"supplierRequired": "未明确",
"processing": "可选,服务补",
"required": false,
"description": "按 C05 补齐并核对",
"type": "string"
},
{
"name": "merchantNo",
"supplierRequired": "未明确",
"processing": "必填",
"required": true,
"description": "授权范围内商户",
"type": "string"
},
{
"name": "orderId",
"supplierRequired": "未明确",
"processing": "必填",
"required": true,
"description": "本服务发起过的订单;其他参数拒绝",
"type": "string"
}
],
"responseFields": [
{
"name": "payAmount",
"supplierRequired": "未明确",
"processing": "上游有则保留",
"required": false,
"description": "除第3.3节付款人删除清单外,上游合法字段原样原类型保留,不补缺失字段;此处仅列设计稿点名字段,不宣称完整官方 schema。"
},
{
"name": "orderAmount",
"supplierRequired": "未明确",
"processing": "上游有则保留",
"required": false,
"description": "除第3.3节付款人删除清单外,上游合法字段原样原类型保留,不补缺失字段;此处仅列设计稿点名字段,不宣称完整官方 schema。"
},
{
"name": "status",
"supplierRequired": "未明确",
"processing": "上游有则保留",
"required": false,
"description": "除第3.3节付款人删除清单外,上游合法字段原样原类型保留,不补缺失字段;此处仅列设计稿点名字段,不宣称完整官方 schema。"
}
],
"uncertainty": [
"未在设计稿明确的字段、类型、必填性和响应层级保持未定义,不根据示例反推 schema。",
"返回表未完整展开;这里只结构化设计稿点名的字段,其他上游合法字段仍原样保留。"
],
"displayFields": [
{
"location": "response",
"label": "同步返回删除清单",
"description": "去掉的付款人字段(产品负责人 11/11 12:49 亚利桑那已定,第 1 节第 4 处例外):返回前删掉顶层的 `userId`、`buyerLogonId`、`yeepayOpenId`、`bankCardNo`,以及 `payerInfo` 整个对象(子字段 `bankId`、`accountName`、`bankCardNo`、`mobilePhoneNo`、`cardType`、`userID`、`buyerLogonId`、`ypAccountBookNo`、`appID`、`channelTrxId`、`bankPostscript`),出现就删,没有就不管;其余字段照旧原样原类型。删除只发生在返回给调用方的那一份;本服务判定用的渠道交易号后 4 位在删除前取出、存进收款单(只在 facts 和推送里给)。另删查单返回 `enterprisePayInfo` 里的 `enterpriseId`(付款企业的账户 id,只在支付宝企业码支付时出现),对象里其余字段保留。判断标准:能认出具体付款人或其账户的删(账号、卡号、手机号、姓名、openid、企业账户 id);只说明支付方式的不删。顶层的 `channelTrxId`(完整渠道交易号)、`appID`、`cardType`、`payBank` 是易宝自己的顶层字段,原样返回,不截短、不删(日志里“`channelTrxId` 只留后 4 位”的规则只管日志和推送,不用于同步返回)。查单里的 `cardType`、`bankId` 在 `payerInfo` 里,跟着整个对象一起删,和付款码顶层保留的不一样,收银台要用请 Lihao 提出。这份清单来自易宝通知文档、11/11 核对和 Claude 第 8 轮对在线返回表的复核;P2 实现前按当天的付款码、查单在线返回表再逐个核对,P4 实现前对退款、查退款(含 `channelReceiverInfo`)同样核对,按上面的标准处理,变化写进对应 PR。"
}
],
"keyRules": [
{
"title": "查询行为(建议)",
"items": [
"只查本应用授权范围内、本服务发起过的订单;不认识的 orderId 回 404 `NOT_FOUND`,不替调用方查别人的单。",
"每次请求在预算内实时查易宝原账户、原商户、原订单;同一订单有进行中的查询时,等它的结果(最多到本次预算),不并发打易宝。",
"查到的结果和本地已确认的事实一致:HTTP 200,返回易宝查单业务结果(官方返回表的全部字段原样原层级原类型,第 6.2 节)。不加本服务自己的字段(包括 `channel_trade_no_last4`,它只在 facts 接口和第二跳推送里给,第 17 节 GPAY02-07);删掉付款人字段,清单和规则同第 3.3 节(产品负责人 11/11 12:49 亚利桑那已定)。",
"和本地已确认事实矛盾(如本地已成功、这次查到 FAIL):不返回渠道结果,回 409 `EVIDENCE_CONFLICT`(第 5 节),内部标待核、告警。",
"超时、坏签、缺必要字段:504 / 502(第 5 节),不返回半截结果。"
]
},
{
"title": "入口判断顺序(11/11复审统一)",
"items": [
"本页是 GET,参数放在规范查询串中,不执行 POST 的 Content-Type/query 检查,从检查鉴权头和时间戳开始。",
"鉴权头齐全 → 否则 401,`missing_auth_header`;时间戳在 ±300 秒内 → 否则 401,`timestamp_out_of_window`。",
"规范性:严格解析(每对一个 `=`、编码规范、`+` 拒绝、重复键拒绝)→ 否则 401,`non_canonical`。",
"验签 → 否则 401,`invalid_signature`。",
"认领 nonce(600 秒窗口)→ 重用 401,`nonce_reused`;nonce 表抢锁失败 401,`nonce_unavailable`。",
"授权范围(`merchantNo` 等是否属于本应用)→ 403 `SCOPE_DENIED`。",
"字段白名单和取值校验 → 422 `VALIDATION_FAILED`;之后才进业务、调渠道。"
]
},
{
"title": "渠道交易号后4位的位置",
"items": [
"A3原样返回易宝业务结果,不添加channel_trade_no_last4;该本服务字段只在facts和第二跳推送提供,成功单有值,其余null(第3.5、12、17节)。"
]
},
{
"title": "401原因与响应头",
"items": [
"401 的机器可读原因(Lihao 11/11 要求,POS 据此分清表单配置问题和签名问题):返回 `{\"error\":{\"code\":\"UNAUTHENTICATED\",\"message\":\"…\",\"details\":{\"reason\":\"<原因>\"}}}`,`reason` 取上面 1—5 步的值之一:`invalid_content_type`、`query_not_allowed`、`missing_auth_header`、`timestamp_out_of_window`、`non_canonical`、`invalid_signature`、`nonce_reused`,另加下面归并规则里的 `nonce_unavailable`。日志第①段 `auth_result` 用同一套取值(第 13.1 节)。`reason` 只说哪一步没过,不回显期望的签名或待签串。归并规则:鉴权头缺失、重复、格式不对(时间戳不是数字、nonce 长度不对等),以及新接口上 `X-SP-Sign-Version` 缺失或不是 `2`,都算 `missing_auth_header`;应用标识不认识或已停用算 `invalid_signature`(不暴露应用是否存在);nonce 表抢锁失败(第 5 节保留的那种 401)也回 401,但不算重放,`reason` 用 `nonce_unavailable`(第八个值,日志同名),调用方可以换新 nonce 重签再发。401 响应带 `WWW-Authenticate: SP-Sign version=\"2\"` 头。"
]
},
{
"title": "同步返回付款人信息处理",
"items": [
"去掉的付款人字段(产品负责人 11/11 12:49 亚利桑那已定,第 1 节第 4 处例外):返回前删掉顶层的 `userId`、`buyerLogonId`、`yeepayOpenId`、`bankCardNo`,以及 `payerInfo` 整个对象(子字段 `bankId`、`accountName`、`bankCardNo`、`mobilePhoneNo`、`cardType`、`userID`、`buyerLogonId`、`ypAccountBookNo`、`appID`、`channelTrxId`、`bankPostscript`),出现就删,没有就不管;其余字段照旧原样原类型。删除只发生在返回给调用方的那一份;本服务判定用的渠道交易号后 4 位在删除前取出、存进收款单(只在 facts 和推送里给)。另删查单返回 `enterprisePayInfo` 里的 `enterpriseId`(付款企业的账户 id,只在支付宝企业码支付时出现),对象里其余字段保留。判断标准:能认出具体付款人或其账户的删(账号、卡号、手机号、姓名、openid、企业账户 id);只说明支付方式的不删。顶层的 `channelTrxId`(完整渠道交易号)、`appID`、`cardType`、`payBank` 是易宝自己的顶层字段,原样返回,不截短、不删(日志里“`channelTrxId` 只留后 4 位”的规则只管日志和推送,不用于同步返回)。查单里的 `cardType`、`bankId` 在 `payerInfo` 里,跟着整个对象一起删,和付款码顶层保留的不一样,收银台要用请 Lihao 提出。这份清单来自易宝通知文档、11/11 核对和 Claude 第 8 轮对在线返回表的复核;P2 实现前按当天的付款码、查单在线返回表再逐个核对,P4 实现前对退款、查退款(含 `channelReceiverInfo`)同样核对,按上面的标准处理,变化写进对应 PR。"
]
}
],
"authDescription": "本服务签名 v2(第4.1、4.3节):HMAC-SHA256,签名覆盖规范查询串、原始正文和Content-Type;应用→品牌/门店→商户授权核对。"
}
},
"diagnostics": {
"networkEnabled": false,
"documentationOnly": true
},
"businessRules": [
"调用方使用本服务签名而非 YOP,易宝 SDK 不能零改动直连。",
"易宝回调先到本服务再签名推给调用方,不是字节级透传。",
"安全错误使用本服务 error 外层,不冒充易宝 code;业务结果不加 data/meta。",
"只支持门店直收;不支持的官方字段明确拒绝,未知字段也拒绝。",
"门店已确认是品牌总部下的入驻商户(SETTLED_MERCHANT);默认 parentMerchantNo 为品牌总部的平台商编,与 merchantNo 不同。标准商户同编是另一种按商编配置;教练、供应链、商户池类型仍待确认,第一阶段不收款,不默认任何类型。",
"产品负责人11/11 12:49已定:同步返回删除第3.3节付款人字段,其余易宝字段原样原类型;理由是付款人信息不保留。顶层完整channelTrxId不截短,日志及推送的后4位规则不用于同步返回。"
],
"issues": [
"未在设计稿明确的字段、类型、必填性和响应层级保持未定义,不根据示例反推 schema。",
"返回表未完整展开;这里只结构化设计稿点名的字段,其他上游合法字段仍原样保留。"
]
}