API 付款交易

请求

付款 API 使商户能够向各类收款人（员工、客户、供应商、合作伙伴等）发起付款。此 API 支持多种支付方式，用于越南市场的安全、高效资金转账。

请求路径：

沙盒：https://sandbox-gateway.smilepayz.com/v2.0/disbursement/pay-out
生产：https://gateway.smilepayz.com/v2.0/disbursement/pay-out

请求头参数

字段	必填	类型	描述
Content-Type	M	String	HTTP 内容类型，固定值：application/json
X-TIMESTAMP	M	String	ISO 8601 日期时间，带时区 示例：2020-12-17T10:55:00+07:00 须为当前服务器时间，误差在 ±5 分钟内
X-SIGNATURE	M	String	请求认证用数字签名 参见签名生成
X-PARTNER-ID	M	String	平台分配的唯一商户标识 请填写 merchantID

请求体参数

字段	必填	类型	描述
orderNo	M	String(32)	唯一交易标识 长度：6–32 字符，仅字母与数字 用于交易跟踪与参考
purpose	M	String(64)	交易目的或说明 UTF-8，最长 64 字符
merchant	M	Object	商户信息 参见商户模型
merchantId	M	String	商户 ID
merchantName / subMerchantId / subMerchantName	O	String	商户名称、子商户 ID/名称（可选）
money	M	Object	交易金额与币种 参见货币模型
currency	M	String	固定值：VND（越南盾）
amount	M	Number	最小货币单位金额 示例：20000 表示 20000 VND 范围：50000–5000000 仅供参考，实际限制受下游渠道影响可能有所不同。
paymentMethod	M	String(6)	支付方式代码 示例：ABB、ACB、VCB 等 参见支付方式列表
cashAccount	M	String(32)	越南银行账号或电子钱包标识 字母数字，最长 32 字符 资金转入目标
receiver	M	Object	收款人信息 参见收款人模型
name	M	String	收款人全名
phone	M	String	收款人手机号 示例：845965823652
email	M	String	收款人邮箱
callbackUrl	O	String(256)	交易状态回调 URL 用于实时状态通知

重要说明

1. 订单号： orderNo 在商户维度内须唯一
2. 金额： 以最小货币单位（越南盾）提供；范围与限制仅供参考，受下游渠道影响可能有所不同。
3. 时区： 时间戳使用越南时区（UTC+7）
4. 账户： 须为有效的越南银行账号或电子钱包标识
5. 支付方式： 支持主流越南银行与电子钱包，见支付方式列表
6. 收款人： 姓名、手机、邮箱均为必填

请求体示例

以下示例中字段取值仅供参考，实际以接口为准。

Content-type: application/json
X-TIMESTAMP: 2020-12-17T10:55:00+07:00
X-SIGNATURE: 7MHd9v5/m9JeqmDZVwWBZUZ5J5...7120QnFEny7Qm7uQR1G0TWCh10fsU6nVxiRoeoQ==
X-PARTNER-ID: 20001

{
    "cashAccount": "09171234567",
    "receiver": {
        "name": "Maria Santos Cruz",
        "phone": "845965823652",
        "email": "[email protected]"
    },
    "merchant": {
        "merchantId": "20001"
    },
    "money": {
        "amount": 50000,
        "currency": "VND"
    },
    "orderNo": "2000102900000000000001",
    "paymentMethod": "ABB",
    "purpose": "2024年3月工资发放"
}

响应

HTTP 响应

字段	必填	类型	描述
Content-Type	M	String	固定值：application/json
X-TIMESTAMP	M	String	ISO 8601 日期时间，带时区（UTC+7）

响应体参数

字段	必填	类型	描述
code	M	String	状态码，00 表示成功
message	M	String	状态说明
orderNo	M	String	与请求一致的订单号
tradeNo	O	String	系统内部交易号
merchant	M	Object	商户信息
money	M	Object	确认金额与币种（VND）
disbursementTime	M	String	付款完成时间 格式：yyyy-MM-ddTHH:mm:ss
channel	M	Object	支付渠道信息 参见渠道模型
status	O	String	当前状态 参见状态模型

以下响应体示例仅供参考，实际字段取值以接口为准。

Content-type: application/json
X-TIMESTAMP: 2020-12-17T10:55:00+07:00

{
  "code": "00",
  "message": "成功",
  "orderNo": "2000102900000000000001",
  "tradeNo": "1822000109e998347483949",
  "merchant": {
    "merchantId": "20001",
    "merchantName": "test",
    "accountNo": "2000124234782342"
  },
  "money": {
    "currency": "VND",
    "amount": 20000
  },
  "disbursementTime": "2024-12-17T10:55:00",
  "channel": {
    "paymentMethod": "ABB",
    "cashAccount": "09171234567",
    "accountName": "Maria Santos Cruz"
  },
  "status": "PROCESSING"
}

回调通知

HTTP 请求

字段	必填	类型	描述
Content-Type	M	String	固定值：application/json
X-TIMESTAMP	M	String	ISO 8601 日期时间，带时区 示例：2020-12-17T10:55:00+07:00
X-SIGNATURE	M	String	回调认证用数字签名 参见回调签名验证

回调体参数

字段	必填	类型	描述
orderNo	M	String	商户订单号，与请求一致，用于交易识别与核对
tradeNo	M	String	系统内部交易参考号，用于跟踪与支持
merchantId	M	String	平台分配的唯一商户标识
merchantName	M	String	商户名称或展示名，UTF-8 编码
subMerchantId	O	String	子商户标识（多级商户时使用）
subMerchantName	O	String	子商户名称或展示名
paymentMethod	M	String	实际支付方式代码，如 ABB 参见支付方式列表
transactionTime	M	String	交易完成时间 格式：yyyy-MM-ddTHH:mm:ss
money	M	Object	确认金额与币种
currency	M	String	固定值：VND（越南盾）
amount	M	Number	最小货币单位金额 范围：50000–5000000 仅供参考，受下游渠道影响可能有所不同。
status	M	String	终态：SUCCESS、FAILED、CANCELLED 参见状态模型

回调响应

重要

通知响应： 请仅返回字符串 SUCCESS 表示已收到通知

以下回调体示例仅供参考，实际字段取值以接口为准。

{
  "orderNo": "2000102900000000000001",
  "tradeNo": "1522000109e998347483949",
  "merchantId": "20001",
  "merchantName": "test",
  "subMerchantId": "",
  "subMerchantName": "",
  "paymentMethod": "ABB",
  "transactionTime": "2024-12-17T10:55:00",
  "money": {
    "currency": "VND",
    "amount": 20000
  },
  "status": "SUCCESS"
}

SUCCESS