API 收款交易

USDT地区 收款（Pay-in） 接口（USDT）。详见支付方式。

请求

收款 API 使商户能够向客户发起收款交易。此 API 支持各种加密货币支付方式，用于安全高效的数字资产收款。

请求路径：

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

请求头参数

字段	必填	类型	描述
Content-Type	是	String	HTTP 内容类型规范固定值：application/json 用于正确解析请求
X-TIMESTAMP	是	String	ISO 8601 日期时间格式，带时区偏移格式：yyyy-MM-ddTHH:mm:ss±HH:mm 示例：2020-12-17T10:55:00+07:00 注意：必须是当前服务器时间，误差在 ±5 分钟内
X-SIGNATURE	是	String	请求认证的数字签名参见签名生成
X-PARTNER-ID	是	String	Your merchantID

请求体参数

字段	必填	类型	描述
orderNo	是	String(32)	唯一交易标识符格式：字母数字字符串（仅数字和字母）长度：6-32 个字符用于交易跟踪和参考
purpose	是	String(64)	交易目的或描述格式：UTF-8 编码字符串最大长度：64 个字符用于交易识别和报告
merchant	是	Object	商户信息容器包含商户识别和业务详情参见商户模型
merchantId	是	String	平台分配的唯一商户标识符格式：字母数字字符串用于商户认证和交易路由
merchantName	否	String	商户业务名称或显示名称格式：UTF-8 编码字符串用于商户识别和报告
subMerchantId	否	String	多级商户结构的子商户标识符格式：字母数字字符串用于子商户识别和报告
subMerchantName	否	String	子商户业务名称或显示名称格式：UTF-8 编码字符串用于子商户识别和报告
money	是	Object	带货币规范的交易金额详情包含交易金额和货币信息参见货币模型
currency	是	String	ISO 4217 货币代码规范固定值：USDT（泰达币）确定支付处理规则和结算货币
amount	是	Number	金额
network	是	String	数字货币的区块链网络规范格式：预定义网络代码示例：ERC20, BEP20, TRC20 表示交易处理的区块链网络
productDetail	否	String(128)	产品或服务描述格式：UTF-8 编码字符串最大长度：128 个字符用于交易识别和报告
paymentMethod	否	String	用于交易处理的支付方式格式：预定义支付方式代码示例：WALLET 表示实际使用的支付渠道参见支付方式列表
expiryPeriod	否	Number	ExpiryPeriod，默认 3600。
redirectUrl	否	String(256)	支付完成后客户重定向 URL 格式：有效的 HTTP/HTTPS URL 最大长度：256 个字符用于支付处理后重定向客户
callbackUrl	否	String(256)	交易状态更新的 Webhook 通知 URL 格式：有效的 HTTP/HTTPS URL 最大长度：256 个字符用于实时交易状态通知

请求体示例 – 交易请求：

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

{
  "network": "TRC20",
  "merchant": {
    "merchantId": "20001",
    "merchantName": "Smilepayz Demo Store"
  },
  "payer": {
    "phone": "+66812345678",
    "email": "[email protected]"
  },
  "money": {
    "amount": 100,
    "currency": "USDT"
  },
  "orderNo": "20001usdtwallet98b010db244c99d",
  "paymentMethod": "WALLET",
  "purpose": "Crypto checkout — demo invoice",
  "redirectUrl": "https://docs.smilepayz.com/en/"
}

响应

HTTP 响应

字段	必填	类型	描述
Content-Type	是	String	HTTP 响应内容类型规范固定值：application/json 表示 JSON 响应格式
X-TIMESTAMP	是	String	ISO 8601 日期时间格式，带时区偏移格式：yyyy-MM-ddTHH:mm:ss±HH:mm 示例：2020-12-17T10:55:00+07:00

响应体参数

字段	必填	类型	描述
code	是	String	API 响应状态码，表示操作结果格式：两位数字字符串成功："00"，错误：其他代码用于程序化响应处理
message	是	String	人类可读的响应状态描述格式：UTF-8 编码字符串提供操作结果的详细信息根据请求语言进行本地化
orderNo	是	String	请求中提供的唯一交易标识符格式：字母数字字符串与请求中提供的 orderNo 相同用于交易跟踪和参考
merchant	是	Object	商户信息容器包含商户识别和业务详情参见商户模型
merchantId	是	String	平台分配的唯一商户标识符格式：字母数字字符串用于商户认证和交易路由
merchantName	否	String	商户业务名称或显示名称格式：UTF-8 编码字符串用于商户识别和报告
subMerchantId	否	String	多级商户结构的子商户标识符格式：字母数字字符串用于子商户识别和报告
subMerchantName	否	String	子商户业务名称或显示名称格式：UTF-8 编码字符串用于子商户识别和报告
money	是	Object	带货币规范的交易金额详情包含确认的交易金额和货币参见货币模型
currency	是	String	ISO 4217 货币代码规范固定值：USDT（泰达币）确定支付处理规则和结算货币
amount	是	Number	金额
transactionTime	是	String	交易完成时间戳格式：yyyy-MM-ddTHH:mm:ss 示例：2020-12-17T10:55:00+07:00 用于交易时间和审计
channel	是	Object	支付渠道信息容器包含支付方式和处理详情参见渠道模型
tradeNo	否	String	系统跟踪的内部交易参考号格式：系统生成的字母数字字符串用于内部交易管理和支持
status	否	String	当前交易处理状态格式：预定义状态代码示例：PROCESSING, SUCCESS, FAILED, CANCELLED 表示交易的当前状态参见状态模型

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

{
    "channel": {
        "paymentMethod": "WALLET",
        "paymentUrl": "https://gateway-test.smilepayz.com/cashier/#/loading?tradeNo=3012003025112812141312194",
        "cardData": {
            "payeeBankCard": "TS8taf44vwibX7z4vE7aqrA7xVQjzzGKoZ",
            "payAmount": 100.0,
            "network": "TRC20"
        }
    },
    "merchant": {
        "accountNo": "11120001202406101410",
        "merchantId": "20001",
        "merchantName": "Smilepayz Demo Store"
    },
    "money": {
        "amount": 100,
        "currency": "USDT"
    },
    "orderNo": "20001usdtwallet98b010db244c99d",
    "tradeNo": "3012003025112812141312194",
    "status": "PROCESSING",
    "transactionTime": "2024-11-19T12:51:47+07:00",
    "code": "00",
    "message": "Successful",
    "responseCode": "2009000",
    "responseMessage": "Successful"
}

通知

HTTP 请求

字段	必填	类型	描述
Content-Type	是	String	HTTP 请求内容类型规范固定值：application/json 表示 JSON 请求格式
X-TIMESTAMP	是	String	ISO 8601 日期时间格式，带时区偏移格式：yyyy-MM-ddTHH:mm:ss±HH:mm 示例：2020-12-17T10:55:00+07:00
X-SIGNATURE	是	String	通知认证的数字签名参见回调签名验证

请求体参数

字段	必填	类型	描述
orderNo	是	String	商户交易标识符格式：字母数字字符串与原始请求中提供的 orderNo 相同用于交易识别和验证
tradeNo	是	String	系统跟踪的内部交易参考号格式：系统生成的字母数字字符串用于内部交易管理和支持
merchantId	是	String	平台分配的唯一商户标识符格式：字母数字字符串用于商户认证和交易路由
merchantName	是	String	商户业务名称或显示名称格式：UTF-8 编码字符串用于商户识别和报告
subMerchantId	否	String	多级商户结构的子商户标识符格式：字母数字字符串用于子商户识别和报告
subMerchantName	否	String	子商户业务名称或显示名称格式：UTF-8 编码字符串用于子商户识别和报告
paymentMethod	是	String	用于交易处理的支付方式格式：预定义支付方式代码示例：USDT, BTC, ETH 表示实际使用的支付渠道
transactionTime	是	String	交易完成时间戳格式：yyyy-MM-ddTHH:mm:ss 示例：2020-12-17T10:55:00+07:00 用于交易时间和审计
status	是	String	最终交易处理状态格式：预定义状态代码示例：SUCCESS, FAILED, CANCELLED 表示交易的最终状态参见状态模型
money	是	Object	带货币规范的交易金额详情包含确认的交易金额和货币参见货币模型
currency	是	String	ISO 4217 货币代码规范固定值：USDT（泰达币）确定支付处理规则和结算货币
amount	是	Number	金额
payer	是	Object	付款人信息容器包含客户识别和联系详情参见付款人模型

重要响应

通知响应： 请仅返回字符串 SUCCESS 以确认收到通知

{
  "orderNo": "20001usdtwallet98b010db244c99d",
  "tradeNo": "3012003025112812141312194",
  "merchantId": "20001",
  "merchantName": "Smilepayz Demo Store",
  "subMerchantId": "",
  "subMerchantName": "",
  "paymentMethod": "WALLET",
  "transactionTime": "2024-11-19T12:51:47+07:00",
  "status": "SUCCESS",
  "money": {
    "currency": "USDT",
    "amount": 100
  },
  "payer": {
    "name": "Demo Payer",
    "email": "[email protected]"
  }
}

SUCCESS

API 收款交易

# 请求

# 请求路径：

# 请求头参数

# 请求体参数

# 请求体示例 – 交易请求：

# 响应

# HTTP 响应

# 响应体参数

# 通知

# HTTP 请求

# 请求体参数

# 返回

请求

请求路径：

请求头参数

请求体参数

请求体示例 – 交易请求：

响应

HTTP 响应

响应体参数

通知

HTTP 请求

请求体参数

返回