API 收款交易

请求

收款 API 使商户能够发起向客户收取付款的交易。此 API 支持多种支付方式，用于越南市场的安全、高效资金收取。

请求路径：

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

请求头参数

字段	必填	类型	描述
Content-Type	M	String	HTTP 内容类型规范固定值：application/json 正确解析请求所必需
X-TIMESTAMP	M	String	ISO 8601 日期时间格式，带时区偏移格式：yyyy-MM-ddTHH:mm:ss±HH:mm 示例：2020-12-17T10:55:00+08: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	平台分配的唯一商户标识用于商户认证与交易路由
merchantName	O	String	商户名称或展示名格式：UTF-8 字符串
subMerchantId	O	String	子商户标识（多级商户时使用）
subMerchantName	O	String	子商户名称或展示名
money	M	Object	交易金额与币种参见货币模型
currency	M	String	ISO 4217 货币代码固定值：VND（越南盾）决定处理规则与结算货币
amount	M	Number	最小货币单位金额示例：20000 表示 20000 VND 范围：20000–20000000 仅供参考，实际限制受下游渠道影响可能有所不同。
paymentMethod	O	String	支付方式代码示例：W_MOMO、W_ZALO、W_VIETTEL、VIET_QR 参见支付方式列表
expiryPeriod	O	Number	交易有效时长（秒）默认：3600（1 小时）最大：86400（24 小时）仅供参考，实际取值受下游渠道影响可能有所不同。
redirectUrl	O	String(256)	支付完成后跳转 URL 有效 HTTP/HTTPS，最长 256 字符
callbackUrl	O	String(256)	交易状态回调 URL 用于接收实时状态通知

请求体示例

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

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

{
    "merchant": {
        "merchantId": "20011"
    },
    "money": {
        "amount": 20000,
        "currency": "VND"
    },
    "orderNo": "200110edbb466abb04682968b40",
    "paymentMethod": "W_MOMO",
    "purpose": "在线购买支付",
    "redirectUrl": "https://www.example.com/success"
}

响应

HTTP 响应

字段	必填	类型	描述
Content-Type	M	String	固定值：application/json
X-TIMESTAMP	M	String	ISO 8601 日期时间，带时区示例：2020-12-17T10:55:00+08:00

响应体参数

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

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

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

{
    "code": "00",
    "message": "成功",
    "tradeNo": "1812001125042115424463245",
    "orderNo": "20011563d9094aa7d4d9e9b933bb",
    "merchant": {
        "merchantId": "20011",
        "merchantName": "bradytest123www",
        "accountNo": "11820011202403071031"
    },
    "money": {
        "currency": "VND",
        "amount": 20000
    },
    "transactionTime": "2025-06-19T10:31:33+08:00",
    "channel": {
        "paymentMethod": "W_MOMO",
        "paymentUrl": "https://gateway.smilepayz.com/cashier/#/loading?tradeNo=1812003025061909313195096"
    },
    "status": "PROCESSING"
}

回调通知

HTTP 请求

字段	必填	类型	描述
Content-Type	M	String	固定值：application/json
X-TIMESTAMP	M	String	ISO 8601 日期时间，带时区
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	实际支付方式代码，如 W_MOMO 参见支付方式列表
transactionTime	M	String	交易完成时间格式：yyyy-MM-ddTHH:mm:ss
money	M	Object	确认金额与币种
currency	M	String	固定值：VND（越南盾）
amount	M	Number	最小货币单位金额范围：20000–2000000 仅供参考，受下游渠道影响可能有所不同。
status	M	String	终态：SUCCESS、FAILED、CANCELLED 参见状态模型

回调响应

重要

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

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

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

SUCCESS

API 收款交易

# 请求

# 请求路径：

# 请求头参数

# 请求体参数

# 请求体示例

# 响应

# HTTP 响应

# 响应体参数

# 回调通知

# HTTP 请求

# 回调体参数

# 回调响应

请求

请求路径：

请求头参数

请求体参数

请求体示例

响应

HTTP 响应

响应体参数

回调通知

HTTP 请求

回调体参数

回调响应