# 开放接口附录：常见参数与路由错误排查

> 下列与开放接口下单/代付时的**参数校验、路由失败**相关。完整业务码表见 `website/pay-codes-zh-CN.json` 及 `api-docs.html`「PAY 业务码全表」。排障时以**实际响应**的 `rspCode`、`rspMsg` 为准。

## 1. 与 `payTypeCode` / 国家 / `payMethodCode` 不匹配

| rspCode（示例） | 常见原因 | 处理建议 |
|---|---|---|
| `PAY_METHOD_001` | `payTypeCode` 不存在、未开通或已停用 | 对照 `pay-method-type-master.json` 与商户后台开通；确认大小写不敏感但拼写与主数据一致。 |
| `PAY_INTL_001` | `payTypeCode` 对应国家与请求 `country`/`countryCode` 不一致 | 修正国家二字码，或与商务确认该产品是否对该国开放。 |
| `PAY_METHOD_002` | `payMethodCode` 与主数据中该 `payTypeCode` 行不一致 | 按 **`pay-method-type-master.json` / 商户后台** 中该产品对应的 `payMethodCode` 传参；勿仅用大类猜测。 |
| `PAY_PARAM_020` | 业务规则要求 `instrument.bankCode`（或等价）等未传 | 代收：若产品要求银行编码，在 `instrument.bankCode` 等字段补全（见渠道附录）。 |

*上述码在 `PayDictValidationService` 等校验路径中出现；文案以 `rspMsg` 为准。*

## 2. 路由无可用通道

| rspCode | 常见原因 | 处理建议 |
|---|---|---|
| `PAY_ROUTE_001` | 当前 `channelCode` + `country` + `payTypeCode`（及代付收款信息）组合无法解析到可用通道 | 检查 `channelCode` 是否与 **`main-data-reference.json` 中渠道键**或商务约定一致；检查国家、`payTypeCode`、代付 `payeeType` 是否与附录一致；联系平台确认路由与开通。 |

## 3. 代付专项

| 现象 | 可能原因 | 建议 |
|---|---|---|
| 反复提示银行/身份/手机相关错误 | 该产品下 `payeeBankCode`、`payeeBranchName`、`payeeIdCard`、`payeeMobile` 条件必填未满足 | 打开对应渠道 **代付 pay_type_code 附录**，按国别/产品补全字段。 |
| `channelCode` 相关错误 | 漏传或传错渠道 | 代付 **必填** `channelCode`；取值见 `main-data-reference.json` 中 `providers` 或商务约定。 |

## 4. 签名与信封（非路由，但易与参数问题混淆）

| 类型 | 参考码（示例） | 说明 |
|---|---|---|
| 签名错误 | `PAY_SIGN_001` | 参与签名字段、空值排除、`ext` 扁平化与文档一致。 |
| 时间戳/nonce | `PAY_012`、`PAY_PARAM_007` 等 | 见统一协议说明；非路由问题。 |

## 5. 推荐排查顺序

1. 读响应 `rspCode`、`rspMsg`。  
2. 核对 **`payTypeCode` + 国家 + `payMethodCode`（+ 代付 `channelCode`）** 与主数据/附录是否一致。  
3. 若仍失败，对照 **`开放接口附录-路由字段语义说明.md`** 与各渠道 **pay_type_code 附录** 补全条件字段与 `ext`。  
4. 需要全量码表时，使用 `pay-codes-zh-CN.json` 或联系平台索取《返回值与错误码约定》。

---

*文档版本：与仓库 `website/` 同步维护。*