代收订单 · 越南
大约 6 分钟
概述
代收 API 用于向客户发起代收交易。本页为 越南（国家码 vn）的代收能力说明，支持以下两种下单方式：
| 下单方式 | 路径 | 说明 |
|---|---|---|
| 收银台模式 | /pay/prePay | 默认模式，返回 cashierUrl，用户跳转平台 H5 收银台完成支付 |
| API 模式 | /pay/transOrder | 请求中必须指定 method，直接返回 payData / payDataType |
method（越南代收方式编码）见 地区支付说明 — 越南。
接入说明
默认开通收银台模式。如需对接 API 模式，请联系客服申请商户白名单后再集成。
请求头
两种模式共用：
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| Content-Type | M | String | HTTP内容类型规范 固定值：application/json 正确解析请求所必需 |
收银台模式（prePay）
商户预下单后获取 cashierUrl，引导用户至平台收银台选择支付方式并完成付款。
请求路径
域名：推荐使用统一域名
openapi.toppayment.com（路径不变）；原国别域名（如global-vn-openapi.toppayment.com）仍可用。
| 环境 | 地址 |
|---|---|
| 沙箱 | https://openapi.toppayment.com/sandbox/vn/pay/prePay |
| 生产 | https://openapi.toppayment.com/vn/pay/prePay |
请求体
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| mchNo | M | String(32) | 商户编号 平台分配的唯一商户标识符 用于商户认证和交易路由 |
| orderNum | M | String(64) | 商户订单号 唯一交易标识符 格式：字母数字字符串 用于交易跟踪和参考 |
| amount | M | Number(32,8) | 交易金额 越南地区不允许小数，请传整数 示例：100000 |
| productDetail | O | String (100) | 产品详情 交易目的或描述 格式：UTF-8编码字符串 |
| method | O | String (16) | 支付方式（越南） 可选；不传则用户在收银台选择。支持 BANK_QR、MOMO、ZALO、VTPAY，见 地区支付说明 — 越南 |
| timestamp | M | String(13) | 时间戳 请求时间戳（毫秒级） 示例：1749451858772 |
| customerName | O | String (64) | 客户姓名 付款人姓名 格式：UTF-8编码字符串 |
| customerEmail | O | String (64) | 客户邮箱 付款人邮箱地址 格式：有效的邮箱格式 |
| customerPhone | O | String (32) | 客户电话 付款人电话号码 |
| expiryPeriod | O | Number(1-9999) | 过期时间 交易过期时间（分钟） |
| downNotifyUrl | M | String(255) | 异步通知地址 交易状态更新的Webhook通知URL |
| redirectUrl | O | String(512) | 重定向地址 支付完成后客户重定向URL |
| sign | M | String | 签名 请求认证的数字签名 参见签名生成 |
请求体示例
{
"mchNo": "{{mchNo}}",
"orderNum": "VN1232451",
"amount": 100000,
"productDetail": "测试",
"method": "BANK_QR",
"timestamp": "1749451858772",
"customerName": "AMY",
"customerEmail": "[email protected]",
"customerPhone": "0817773255",
"expiryPeriod": 1440,
"downNotifyUrl": "https://123.com",
"redirectUrl": "http://hxxyhyo.mr/gchmnzv",
"sign": "按签名规则生成后替换"
}
响应字段
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| success | M | Boolean | 请求是否成功 true：成功，false：失败 |
| code | M | String | 响应状态码 9999：成功 其他：失败 |
| msg | O | String | 响应消息 |
| timeStamp | M | Number | 响应时间戳（毫秒级） |
| data | M | Object | 响应数据对象 |
| orderNum | M | String | 商户订单号 |
| platOrderNum | M | String | 平台订单号 |
| amount | M | Number | 交易金额 |
| fee | M | Number | 手续费 |
| method | M | String | 支付方式（越南） 以实际返回为准，编码含义见 地区支付说明 — 越南 |
| productDetail | O | String | 产品详情 |
| customerName | O | String | 客户姓名 |
| customerEmail | O | String | 客户邮箱 |
| customerPhone | O | String | 客户电话 |
| validTime | M | Number | 有效期时间戳 |
| cashierUrl | M | String | 收银台URL 用于跳转支付的收银台地址 |
响应示例
{
"success": true,
"code": "9999",
"msg": null,
"timeStamp": 1767840272829,
"data": {
"orderNum": "VN1232451",
"platOrderNum": "PRE2009093829059153920",
"amount": 100000,
"fee": 2000.00,
"method": "BANK_QR",
"productDetail": "测试",
"customerName": "AMY",
"customerEmail": "[email protected]",
"customerPhone": "0817773255",
"validTime": 1767926672819,
"cashierUrl": "https://example.cashier/pay"
}
}
API 模式（transOrder）
商户在请求中指定支付方式后，直接向支付通道发起交易，并在响应中返回 payData / payDataType，无需跳转平台 H5 收银台。
请求路径
| 环境 | 地址 |
|---|---|
| 沙箱 | https://openapi.toppayment.com/sandbox/vn/pay/transOrder |
| 生产 | https://openapi.toppayment.com/vn/pay/transOrder |
请求体
与收银台模式相比，差异如下：
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| method | M | String(16) | 支付方式（越南） API 模式必传。支持 BANK_QR、MOMO、ZALO、VTPAY，见 地区支付说明 — 越南 |
其余字段与收银台模式相同。
请求体示例
{
"mchNo": "{{mchNo}}",
"orderNum": "VNAPI1232451",
"amount": 100000,
"productDetail": "测试",
"method": "BANK_QR",
"timestamp": "1749451858772",
"customerName": "AMY",
"customerEmail": "[email protected]",
"customerPhone": "0817773255",
"expiryPeriod": 1440,
"downNotifyUrl": "https://123.com",
"sign": "按签名规则生成后替换"
}
响应字段
公共响应字段（success、code、msg、timeStamp 及 data 中的 orderNum、platOrderNum、amount、fee、method、productDetail、customerName、customerEmail、customerPhone、validTime）与收银台模式相同。API 模式重点关注：
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| payData | M | String | 支付数据 JSON 字符串（各类 payDataType 结构相同），需自行解析（见下方「payData 结构说明」） |
| payDataType | M | String | 内层 payData.payData 的数据类型取值： QR_CODE、QR_URL、CASHIER_URL（见下方说明表） |
payDataType 说明
payDataType 用于声明解析后 JSON 中 payData 字段的含义，请按实际返回值处理，勿写死单一类型：
| payDataType | 内层 payData 含义 |
|---|---|
QR_CODE | 二维码内容（QR 文本），需自行渲染为二维码（当前常见返回） |
QR_URL | 二维码图片链接，直接使用该 URL 展示二维码图片 |
CASHIER_URL | HTTPS 支付页链接，引导用户跳转至该链接完成支付 |
payData 结构说明
越南 payData 在各类 payDataType 下均为一段序列化后的 JSON 字符串，商户需先将其解析为 JSON 对象，再取用以下字段自行渲染收银台或引导用户转账：
| 字段 | 描述 |
|---|---|
| payData | 支付凭证内容，具体含义由外层 payDataType 决定（见上方说明表） |
| accNo | 收款账号 |
| accName | 收款账户户名 |
| accBankName | 收款开户行 |
| paymentCode | 转账备注 / 支付编码 用户转账时需填写，用于上游匹配订单 |
| payAmount | 实际应付金额 可能与下单 amount 存在细微差异，请以此字段为准 |
响应示例
{
"success": true,
"code": "9999",
"msg": null,
"timeStamp": 1767840272829,
"data": {
"orderNum": "VNAPI1232451",
"platOrderNum": "PRE2009093829059153921",
"amount": 100000,
"fee": 2000.00,
"method": "BANK_QR",
"productDetail": "测试",
"customerName": "AMY",
"customerEmail": "[email protected]",
"customerPhone": "0817773255",
"validTime": 1767926672819,
"payData": "{\"payData\":\"00020101021226650016COM.EXAMPLE.QR...\",\"accNo\":\"1234567890\",\"accName\":\"NGUYEN VAN A\",\"accBankName\":\"ACB\",\"paymentCode\":\"ERD5HGFK\",\"payAmount\":\"100000\"}",
"payDataType": "QR_CODE"
}
}
payData 为字符串
上例中 payData 字段的值本身是一段 JSON 文本（已转义），并非 JSON 对象。商户需要对该字符串再做一次 JSON.parse，才能取到 accNo、accName、accBankName、paymentCode、payAmount 等子字段。
通知
两种下单方式的异步通知一致。
HTTP请求
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| Content-Type | M | String | HTTP请求内容类型规范 固定值：application/json |
通知体
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| platOrderNum | M | String | 平台订单号 |
| version | M | String | 版本号（示例：v1） |
| orderNum | M | String | 商户订单号 |
| amount | M | Number | 交易金额 |
| fee | M | Number | 手续费 |
| customerName | O | String | 客户姓名 |
| customerEmail | O | String | 客户邮箱 |
| customerPhone | O | String | 客户电话 |
| status | M | String | 交易状态 取值见 交易状态码 |
| sign | M | String | 回调签名 |
返回
SUCCESS
通知示例
{
"platOrderNum": "PRE2009165141186183168",
"version": "v1",
"orderNum": "VN12324521",
"amount": 100000,
"fee": 2000,
"customerName": "AMY",
"customerEmail": "[email protected]",
"customerPhone": "0817773255",
"status": "SUCCESS",
"sign": "示例签名"
}