付款人资讯通知

系统在首次取得存款人资讯时，会额外推送一个独立通知到商户的 payment_cl_name_notify_url，内含付款人的姓名、银行账号、银行代码。

此通知与收款交易结果通知各自独立：

收款交易结果通知 → 订单进入成功态时触发，推送到 notify_url
付款人资讯通知 → 首次取得付款人资讯时触发，推送到 payment_cl_name_notify_url

一笔订单可能两种通知都收到（独立推送、独立签名、独立回覆）。

使用场景

本通知专为对帐与风控场景设计：

商户需要在订单成功前或成功后尽快拿到付款人身份（姓名、银行账号、开户银行）用于自家对帐系统
风控系统需要比对付款人资讯与会员绑定帐户

触发时机

仅在首次写入 payment_cl_name 时触发。若订单的 payment_cl_name 已存在值（例如上游多次回调），不会重复通知。
触发来源为上游支付渠道的回调或查询接口。并非所有渠道都会提供付款人资讯，若渠道未回传，本通知不会触发。
若订单建立时商户未传入 payment_cl_name_notify_url，即使系统取得付款人资讯，也不会触发本通知（只更新本系统 DB）。

如何启用

在创建收款单时，额外传入 payment_cl_name_notify_url 参数（可选）：

{
  "platform_id": "PF0002",
  "service_id": "SVC0015",
  "payment_cl_id": "DEVPM00014581",
  "amount": "50000000",
  "notify_url": "https://merchant.example.com/webhook/deposit",
  "payment_cl_name_notify_url": "https://merchant.example.com/webhook/payer-info",
  "request_time": "1595504136",
  "sign_type": "HMAC-SHA256",
  "sign": "..."
}

未传入则不启用本通知。

请求资讯

请求 URL： 商户于申请收款时填入的 payment_cl_name_notify_url
请求方式： POST
Content-Type： application/json;charset=utf-8

请求参数

参数名	必选	类型	说明
payment_id	是	String	系统订单号
payment_cl_id	是	String	商户订单号
payment_cl_name	是	String	付款人姓名
payment_cl_number	否	String	付款人银行账号
payment_cl_bank_name	否	String	付款人开户银行代码（参考越南银行列表）
sign	是	String	订单签名（目前为 MD5，详见下方「签名算法」）

字段规则

payment_cl_name：渠道回传的付款人姓名原始值，系统不做格式化。
payment_cl_number：付款人银行账号完整号码。部分渠道未提供此字段，届时此参数会省略（不出现于 body）。
payment_cl_bank_name：系统会将上游回传的银行名称或代码统一映射为 越南银行列表 中的 bank_name 代码（如 VCB、MB、TCB）。若上游值无法映射到已知银行，此参数会省略。

签名算法

本通知目前使用 MD5，将于 2026/05/01 起统一升级为 HMAC-SHA256

本通知是系统中唯一仍使用 MD5 的端点，其他所有通知与 API 请求均已采用 HMAC-SHA256（详见签名说明）。

2026/05/01 起：本通知将切换为 HMAC-SHA256，且 body 会额外包含 sign_type: "HMAC-SHA256" 字段，与其他通知一致。请商户提前准备好 HMAC-SHA256 验签逻辑，届时旧的 MD5 验签将不再适用。

目前签名规则（MD5）：

取 body 中所有非空值字段，排除 sign
按参数名 ASCII 码由小到大排序
以 key=value 形式用 & 连接（不做 URL encoding）
在末尾追加 &{platform_service_sign_key}
对完整字符串做 MD5 哈希
转为 32 位小写十六进制字符串

范例：body 为

{
  "payment_id": "PM00000102",
  "payment_cl_id": "97a968b4a9db497c8c03198e395a38c6",
  "payment_cl_name": "TRAN TRUNG HIEU",
  "payment_cl_number": "10066777777",
  "payment_cl_bank_name": "MB"
}

签名字符串：

payment_cl_bank_name=MB&payment_cl_id=97a968b4a9db497c8c03198e395a38c6&payment_cl_name=TRAN TRUNG HIEU&payment_cl_number=10066777777&payment_id=PM00000102&{platform_service_sign_key}

对此字符串做 MD5 → 小写十六进制，即为 sign。

请求示例

完整资讯（渠道回传完整）

{
  "payment_id": "PM00000102",
  "payment_cl_id": "97a968b4a9db497c8c03198e395a38c6",
  "payment_cl_name": "TRAN TRUNG HIEU",
  "payment_cl_number": "10066777777",
  "payment_cl_bank_name": "MB",
  "sign": "d2e4534fce8c1d1053bbf59fd8ae4464"
}

仅姓名（渠道未提供银行资讯）

{
  "payment_id": "PM00000103",
  "payment_cl_id": "a1c2d3e4f5g6h7i8",
  "payment_cl_name": "NGUYEN VAN A",
  "sign": "8a7b6c5d4e3f2g1h"
}

商户返回

{ "error_code": "0000" }

参数名	类型	说明
error_code	String	返回 "0000" 即表示商户已处理完成

备注

此接口由商户实现，本系统将于首次取得付款人资讯时消费此接口。
与 notify_url 完全独立：两者的触发时机、推送 body、签名都各自独立，商户需分别实作处理端点。
本通知仅通知一次（不重试），商户需确保端点稳定。若端点返回非 2xx，资讯不会重送。
请使用非空值参与签名，且动态取得有返回值的字段，未来可能新增字段（如付款时间、银行分行）。

使用场景​

触发时机​

如何启用​

请求资讯​

请求参数​

字段规则​

签名算法​

请求示例​

完整资讯（渠道回传完整）​

仅姓名（渠道未提供银行资讯）​

商户返回​

备注​