# 开放接口附录 - 变更记录 本文档汇总 `website/` 下**商户可见**开放接口附录与主数据配套文件的修订，便于对接方按日期查阅。统一协议正文以 **`api-docs.html`** 为准；主数据 JSON（`pay-method-type-master.json`、`main-data-reference.json`、`pay-type-code-field-hints.json` 等）变更时，请同步在此追加条目。 --- ## 2026-10-09 - 新增 shijiepay 聚合付 VN/VND 代收与银行代付接入资料（待部署），8个代收SKU映射5类标准支付类型，BANK/APY003账户适配。 - 更新代付字段矩阵、越南银行标准和统一目录：66家上游银行对应67项已核验标准映射，LPB/LVPB兼容。 - 明确代收尝试号与上游流水方向，代付未提供独立流水时保持为空；实际开通以商户能力查询为准。 --- ## 2026-09-16 - **✅ 已新增**：DZXUM 越南 `VN/VND` 完整对接，覆盖 14 个代收 SKU、`bank_mustcode`/MoMo/ZaloPay/ViettelPay/聚合网关平台标准类型及银行代付。 - **✅ 已固化**：平台金额保持分；DZXUM 越南代收与代付只接受正整数 VND，在上游边界执行 `/100` 转换。 - **✅ 已补齐**：43 家越南代付银行映射、三类代收产品银行白名单、初始化与多语言 SQL、双密钥商户示例、开放接口附录和专项回归测试。 - **✅ 已明确**：代收平台订单号 `mchOrderNo` 与上游 `orderNo`、代付平台订单号 `merTransferId` 与上游 `tradeNo` 严格分离。 --- ## 2026-08-17 - **✅ 已完善**：阿根廷 AR/ARS 代付统一平台标准 `payeeType=CBU|CVU`，对应 `payTypeCode=cbu|cvu`；不再接受 `BANK`、`PERSONAL_BANK`、`BANK_CARD`、`E_WALLET`。 - **✅ 已完善**：Kilipay 阿根廷代付 CBU/CVU、Todaypay 阿根廷代付 CVU、CloudPay/KK888Pay/GCTPK/Fzpay 阿根廷代付 CBU 的开放文档与主数据矩阵已同步。 - **✅ 已新增**：`doc/sql/argentina_payout_cbu_cvu_standard.sql` 用于现网 `pay_type` / `pay_method` / 历史订单对齐（SQL 文件已编写，待手动部署）。 --- ## 2026-08-18 - **✅ 已修复**：Todaypay 阿根廷 ARS 代收在商户未传付款人证件时，由平台稳定生成 8 位数字 DNI；商户显式传入时仍须使用 `payerIdType=ID_CARD` 和 8 位 ASCII 数字。 ## 2026-08-16 - **✅ 已完善**：Todaypay 阿根廷 ARS 代收开放标准 `payTypeCode=qr`（上游 QRIS）与 `payTypeCode=bank_transfer`（上游 CVU），两者均要求真实 8 位 DNI。 - **✅ 已完善**：Todaypay 阿根廷代付固定 `payTypeCode=cvu` / `payeeType=CVU` / 上游 `paymentType=CVU`，不要求 `payeeBankCode` 或证件扩展字段。 - **✅ 已新增**：Todaypay ARS CVU 补单通过受保护的后台动作提交 `fixOrder`；受理不直接推进订单终态，仍以验签回调或主动查单为准。 --- ## 2026-08-15 - **✅ 已新增**：代收查询响应返回 `feeAmount`、`feeCurrency`、`merchantFeeRate`，明确手续费金额、币种与商户费率快照。 - **✅ 已新增**：代付查询在已有 `feeAmount` 之外返回 `merchantFeeRate`、`withdrawFeeAmount`。 - **✅ 已明确**：费率使用小数值（如 `0.009` 表示 `0.9%`），金额使用分；上述字段均使用订单创建时锁定的快照并参与响应签名。 - **✅ 已固化**：新代收订单写入合作模式快照；平台上游按实付金额与锁定费率返回本币手续费，自建上游按独立计费快照返回手续费及币种，历史数据不猜测当前配置。 --- ## 2026-08-12 - **✅ 已新增**：gmylhxe 十国代收/代付适配、标准 `payTypeCode` 与标准代付账户类型矩阵。 - **✅ 已同步**：`api-docs.html/.htm`、统一收银台文档、主数据 JSON、代收/代付附录索引和商户配置示例。 - **✅ 已明确**：代收 `custOrderNo/prdOrdNo`、代付 `custOrdNo/casOrdNo` 及回调改名字段方向；回调验签、金额与订单号均失败关闭。 - **✅ 已采集**：8 个国家银行目录页面，482 条唯一可确认映射写入 SQL，157 条歧义或未匹配记录隔离，不猜测进入资金链路。 --- ## 2026-07-29 - **✅ 已新增**：BharatPay 印度 INR UPI 代收、银行/UPI 代付产品，统一使用 `channelCode=bharatpay` 与平台标准 `payTypeCode=upi|bank`。 - **✅ 已明确**：代收尝试单号/代付批次号始终作为上游 `sourceNo`，BharatPay `id` 始终作为上游订单号；提交、查单和回调均校验订单号与金额。 - **✅ 已同步**：渠道初始化与多语言 SQL、加密商户配置示例、IFSC 银行标准、代付字段矩阵、主数据 JSON、统一接口正文及专项接入说明。 - **✅ 已兼容**：CloudPay 智利 CLP 代付优先接受平台标准 `identityType + identityNo`，其中 `identityType` 仅支持 `ID_CARD/TAX_ID`；未传标准证件对时继续兼容 `payeeIdCard`。 - **✅ 已明确**：标准证件对与 `payeeIdCard` 同时存在时直接采用 `identityType + identityNo`，不比较旧字段；最终 RUT 仍须归一化为恰好 9 位数字并映射到上游 `reserve2`。 - **✅ 已补齐**：商户对接标准表明确仅当 `identityType` 与 `identityNo` 均未传时才回退 `payeeIdCard`；标准证件对只传其中一个时直接拒绝。 - **✅ 已统一**：智利 Kilipay 代付必须分别提交 `payeeFirstName + payeeLastName`，平台不拆分 `payeeName`；其他智利渠道优先使用 `payeeName`，未传时才组合完整名/姓。 - **✅ 已修复**：美国 Zeffra 全部代付产品、Eqpay ACH/PayPal/Venmo、SuccessPayV2 PayPal/Venmo 统一要求根字段 `payeeFirstName + payeeLastName`；不再从 `payeeName` 猜测拆分，也不再接受 `ext.firstName/ext.lastName`。 - **✅ 已修复**：直连代付和代付收银台会在建单前排除缺少独立名/姓的渠道路线；Tdaypay 等非强制拆分渠道仍优先使用 `payeeName`，商户提交完整分名时按根字段透传。 --- ## 2026-07-26 - **✅ 已修复**：CloudPay 智利 CLP 代付仅要求 `payeeIdCard` 提交归一化后恰好 9 位的 RUT，不再展示或要求 `identityType/identityNo`。 - **✅ 已明确**：`payeeType=CHECKING/RUT_ACCOUNT/SAVINGS/VISTA` 映射上游 `reserve1=1/2/3/4`，`payeeIdCard` 映射上游 `reserve2`；`VISTA` 于 2026-08-15 按渠道补充枚举新增。 - **✅ 已修复**：CloudPay 代付创建、查单和回调兼容上游返回 `mOrderNo` 或 `merchantOrderNo`；两者都表示平台代付订单号，同时存在但值不一致时失败关闭。 - **✅ 安全边界不变**：发往 CloudPay 的请求仍使用 `mOrderNo`，`orderId` 始终保存为 CloudPay 上游订单号，禁止反向保存。 - **✅ 已同步**：统一接口正文、`api-docs.html/.htm`、代付字段矩阵、代付接入附录及 CloudPay 专项说明。 --- ## 2026-07-20 - **✅ 已新增**：MkPayEasy 巴西 BRL PIX 代收/代付附录，统一使用 `channelCode=mkpayeasy`、`payTypeCode=pix`。 - **✅ 已修改**：代付字段矩阵与 `api-docs.html/.htm` 新增五种平台标准 PIX `payeeType`，明确无需银行编码且统一要求 `payeeIdCard`。 - **✅ 已明确**：内部 `merchantOrderId` 为平台提交单号、`orderId` 为上游单号；代收失败转成功由配置白名单控制，代付失败保持终态。 --- ## 2026-07-14 - **✅ 已修复**：Zeffra 代收附录和主接口文档补齐 `buyerId`、账单、设备、3DS、网站 URL 与卡类 `ext.zeffra.*` 精确字段名、必填条件和签名规则。 - **✅ 已修复**：明确 Zeffra 原支付回调与被动退款回调的我方订单号、上游支付单号、上游退款号映射，退款资金落库成功后才返回 HTTP 200。 - **✅ 已修复**：代付确认状态清除规则、ACH/银行卡标准支付类型代码及 Zeffra 官方在线文档最后采集时间已同步。 --- ## 2026-07-13 - **✅ 已新增**：Zeffra US/USD 代收、代付接入附录，明确平台标准 `payTypeCode`/`payeeType` 与上游产品码隔离。 - **✅ 已修改**：统一代付新增账户有效期、姓名拆分、地址、邮编、生日根字段，并在提交/查询响应增加 `needUserConfirm`、`confirmUrl`。 - **✅ 已修改**：Zeffra ACH 使用通过校验位验证的 9 位 ABA Routing Number；不生成虚假渠道银行映射。 --- ## 2026-07-09 - **✅ 已新增**：TopPay `toppay` 法币 BR/MX/PE/CO 代收/代付产品，补充 TopPay 代收/代付 `pay_type_code` 附录。 - **✅ 已修改**：`payout-field-requirements.json` 与 `api-docs.html` 的代付字段要求同步新增 TopPay BR PIX、MX SPEI、PE BANK/YAPE/PLIN、CO BANK 字段矩阵。 - **✅ 已新增**：TopPay 初始化 SQL、多语言 SQL、PE 银行映射 SQL、商户号和 key 配置示例、接口对接专项说明。 --- ## 2026-06-26 --- ## 2026-06-25 - **✅ 已新增**：XLPay 哈萨克斯坦 KZT 代收/代付产品，新增 `xlpay_kz_acquire_h5`、`xlpay_kz_payout_bank`。 - **✅ 已新增**：XLPay 商户侧代收/代付 `pay_type_code` 附录、渠道专项说明、SQL 初始化脚本和多语言 SQL。 - **✅ 已修改**：`pay-method-type-master.json`、`pay-type-code-field-hints.json`、`payout-field-requirements.json` 与 `api-docs.html` / `api-docs.htm` 同步补齐 XLPay 条目。 --- ## 2026-05-24 - **✅ 已修改**：Fzpay 代付按当前 Fzpay 代收国家/币种补齐覆盖，`payout-field-requirements.json` 更新为 151 条代付产品，其中 Fzpay 46 条。 - **✅ 已修改**：`api-docs.html` / `api-docs.htm` 的「代付字段要求」表同步刷新为按 `channelCode + 国家/币种 + payeeType` 阅读。 - **✅ 已修改**：`开放接口附录-Fzpay代付pay_type_code接入说明.md` 更新巴西 PIX 专项说明：`payeeType` 自动映射 Fzpay `otherpara1=CPF/CNPJ/PHONE/EMAIL/EVP`。 --- ## 2026-04-20 - **✅ 已修改**：新增 **[开放接口附录-代收pay_type_code接入说明.md](./开放接口附录-代收pay_type_code接入说明.md)**、**[开放接口附录-代付pay_type_code接入说明.md](./开放接口附录-代付pay_type_code接入说明.md)**，作为代收/代付总目录入口，链向各渠道 `pay_type_code` 附录与联调文档。 - **✅ 已修改**：新增 **`pay-type-code-field-hints.json`**，为 `api-docs.html` 主数据表中「银行编码类 / 身份类 / 手机类」三列提供与整改方案 §10.1 对齐的补充说明（未单独标注的编码显示为「—」，以渠道附录为准）。 - **说明**：落实 **`doc/83_开放接口文档下游接入视角整改方案_20260418.md`** 中总目录入口、产品目录列增强与附录统一 changelog 等可落地项。 --- ## 既往 - 路由语义、常见排障、各渠道 NovaVexis/CowPay/Eqpay/Fzpay/Ynuopay 代收代付附录等，以各文件文内版本日期与 **`doc/85`** 巡检基线为准；此前未集中记录于本文件。 # 2026-08-25（TarsPay Indonesia） - 新增 `tarspay` 印尼 IDR 代收、代付、查单、余额和双回调对接说明。 - 新增平台标准 `payTypeCode`、代付账户类型、印尼银行码映射、商户密钥配置示例及主 API 文档入口。 - 明确平台订单号为上游 `mchOrderNo`、上游订单号为 `payOrderId`；部分支付、代付退款和订单号不一致均按失败关闭或人工复核处理。 - 在线协议最后采集时间：2026-08-25 22:55:20 Asia/Shanghai。 --- ## 2026-10-10 shijiepay 菲律宾扩展（待部署） 越南与菲律宾共2国；PH10个代收产品、APY001/APY002银行及4种标准钱包代付；97条官方银行记录对齐86个标准码。回调币种按匹配订单/活动尝试推导，双订单号及无流水恢复不变。其余4国缺产品编码，按用户要求暂不对接。