# jcjcpay 越南 VN/VND 接入说明

最后更新：2026-09-15。支持代收、代付、查询及异步通知，实际可用能力以商户开通的路由为准。

## 代收标准支付类型

商户传平台标准 `payTypeCode`，不传 jcjcpay 原始 `model`、`channel` 或渠道前缀 SKU。平台通过 `pay_method.upstream_type_code` 转换上游产品码。

已确认越南综合收银台，商户使用 `payTypeCode=aggregate`。具体可用性以商户已开通路由及平台返回的支付方式为准，内部上游产品码不作为商户入参。

当前没有产品级代收银行目录，未开放 `bank_mustcode`；不能把代付银行清单作为代收银行能力。普通 `bank` 不填写 `bankCode`。MD5 代收需要有效 `returnUrl`。收银链接与原始二维码分开返回，不把链接中的字符串解析为二维码。

## 代付账户与银行

`countryCode=VN`、`currency=VND`、`payTypeCode=bank`，账户类型支持 `BANK`、`BANK_CARD`、`PERSONAL_BANK`。

| 平台字段 | 要求 | 上游 RSA / MD5 对应字段 |
|---|---|---|
| `payeeType` | 上述银行账户标准之一 | 平台标准，不作为上游 SKU 透传 |
| `payeeName` | 银行账户实名姓名，必填 | `bankcardAccountName` / `bank_owner` |
| `payeeAccount` | 银行账号字符串，必填，保留前导零 | `bankcardAccountNo` / `bank_number` |
| `payeeBankCode` | 越南平台标准银行码，必填 | 映射为 `bankCode` / `bank_code` |
| `payeeBankName` | 可选显示信息，不能代替银行码 | 不用于确定上游银行编码 |

银行码见 [越南平台标准银行目录](vietnam-bank-codes.html) 和 [代付银行查询](payout-bank-catalog.html)。例如平台 `VCB` 映射至上游 `Vietcombank`。提交平台标准码；未确认映射的银行须先确认可用性。

## 金额、订单号与状态

平台 API 金额仍为整数分。示例 `amount=10000` 表示 `100.00 VND`，适配器负责转换上游主币金额，商户不要自行乘除。

代收上游 `merchantOrderNo`（RSA）/ `out_trade_no`（MD5）对应平台的**本次提交尝试单号**；上游 `orderNo` / `trade_no` 对应**渠道流水号**。这些字段都不是下游商户自编订单号。平台对外通知继续保留平台订单号与商户订单号既有含义，不要求商户理解重试尝试号。

代付上游 `merchantOrderNo` / `out_trade_no` 对应平台代付订单号，`orderNo` / `trade_no` 对应上游代付流水。受理不代表打款成功，以验签通过的回调或可信查单为准。查询异常不会被当作支付失败自动结算。
代收提交结果不确定时，平台保持处理中并等待回调或补查，避免自动切换渠道造成重复提交。代付在尚未发出请求时遇到配置错误，会按明确失败处理；请求发出后的未知结果继续保持处理中，不提前解冻。

## 协议参考

平台内部支持 [RSA 官方文档](https://merch.jcjcpay.com/api-doc/) 与 [MD5 官方文档](https://merch.jcjcpay.com/api-md5/)，按渠道商户配置明确选择，不自动降级。上游 RSA 通知应答 `success`，MD5 应答 `SUCCESS`；这些仅由平台上游回调端点处理，不改变商户对接的平台通知规范。