NAV
Português

系统描述

本文档规定了接入支付系统使用的报文接口，包括业务处理流程、接口的通信方式、交易报文格式说明等。本文档是面向具有一定开发能力，了解相关计算机语言的接口对接开发、维护和管理人员。

相关术语

平台

平台是指提供支付能力的我司系统。

商户

商户是指接入平台的使用者。

商户号

商户号是商户在交易平台的唯一标识，是用来判断商户在平台合法性的唯一条件。

商户私钥

商户私钥是商户在进行交易请求前，对数据做加密验签使用的密钥。是平台验证商户交易请求合法性的唯一判断条件，商户应当妥善保管加密密钥，如有泄露，应及时联系平台进行处理，避免不必要的损失。

后台异步回调

系统在接收到交易数据处理完成后，交易系统主动发起通知给商户的网站，同时携带处理完成的结果信息反馈给商户网站

币种

币种是平台用来区分货币类型的字段，具体描述见接口描述。

支付类型

支付类型是平台用来区分支付产品类别的字段，具体描述见接口描述

商户订单号

商户订单号是有商户系统每生成一笔订单会产生的一个唯一标识该笔订单的号码，商户必须保证订单号的唯一性

协议规范与规则

传输方式：采用HTTPS传输

提交方式：POST

内容类型：application/json

字符编码：UTF-8

下行签名校验：HMAC(sha256,json_str, secretKey) == header(PAY-SIGN) ;用于校验平台返回的数据签名

上行鉴权校验: HMAC(sha256,json_str, secretKey) == header(PAY-ACCESS-SIGN)

交易金额：默认巴西雷亚尔，入参（请求）两位小数

时间参数：均使用精确到毫秒的13位时间戳，如：1622016572190。时间戳具体是指从格林尼治时间1970年01月01日00时00分00秒起至现在的毫秒数。

回调与接口响应

  1. 接口正常交互时，接口会在header返回PAY-SIGN
  2. 通知回调地址时，会在header传递PAY-SIGN

签名对json对象原始字符串进行hmacSHA256签名，无排序

举例：

  1. 接口正常响应时，只对data的json对象签名
    • 返回示例：{"code":200,"msg":"SUCCESS","data":{"certImgUrl":"","createdAt":1730785433449,"mchTradeNo":"TEST_ORDER_1234567877884466","state":"SUCCESS","tradeNo":"O1853674577155104768"}}
    • 以上述返回为例，只对这一部分签名 {"certImgUrl":"","createdAt":1730785433449,"mchTradeNo":"TEST_ORDER_1234567877884466","state":"SUCCESS","tradeNo":"O1853674577155104768"}
  2. 回调通知时，对请求body中整个json字符串进行hmacSHA256签名，无排序
  3. 校验hmac(sha256, jsonString , secretKey) == header(PAY-SIGN)

接口鉴权

签名说明

使用参数签名调用接口示例：

curl --request POST \
     --url ${HOST}/api/v1/account/balance \
     --header 'PAY-ACCESS-MCHNO: YourMchNo' \
     --header 'PAY-ACCESS-TIMESTAMP: 1733712250562' \
     --header 'PAY-ACCESS-SIGN: 22582bd0cff14c41edbf1ab98506286d' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{"currency":"XXX","reqTime":1733712250562}'

发起请求：

所有REST私有请求头都必须包含以下内容：

PAY-ACCESS-MCHNO 字符串类型的mchNo商户号。

PAY-ACCESS-TIMESTAMP 发起请求的毫秒时间戳（UTC时区），如： 1733712250562

PAY-ACCESS-SIGN 使用HMAC SHA256哈希函数获得哈希值，字母都小写。

所有请求都应该含有application/json类型内容，并且是有效的JSON。

签名：

PAY-ACCESS-SIGN 的请求头是对timestamp + body字符串（+表示字符串连接），以及SecretKey，使用HMAC SHA256方法加密而得到的（签名字符串的字母都小写）。

如：sign=CryptoJS.HmacSHA256(timestamp + '{"currency":"XXX","amount":"1.23","reqTime":1733712250562}', SecretKey)

注意：json字符串不需要排序，body传什么就拼接签名什么

其中，timestamp的值与PAY-ACCESS-TIMESTAMP请求头相同，为毫秒时间戳格式，如： 1733712250562

body是指请求主体的字符串（body不需要排序，body传什么就拼接签名什么），如果请求没有主体则body可省略。如： {"currency":"XXX","amount":"1.23","reqTime":1733712250562}

币种说明

支持的主链

主链 描述
TRX 波场(Tron)

支持的币种

币种 描述
USDT Tether USD

账户接口

查询账户余额

请求URL：/api/v1/account/balance

请求方式：POST

请求类型：application/json

请求示例

{
    "currency": "USDT",
    "reqTime": 1726306060918
}

请求参数

参数名 类型 必传 描述
currency String 是 货币编码
reqTime Int 是 请求接口时间,13位毫秒时间戳

返回示例

{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "balance": "1001500060",
        "currency": "USDT",
        "frozenBalance": "0",
        "settlementBalance": "0"
    }
}

返回参数

参数名 类型 必传 描述
balance String 是 余额
frozenBalance String 是 冻结余额
settlementBalance String 是 结算中余额,在支付完成、代付退款完成后一分钟内同步到余额帐户"balance"
currency String 是 货币代码

代收接口

代收下单

请求URL：/api/v1/blockchain/charge

请求方式：POST

请求类型：application/json

请求示例

{
  "chain": "TRX",
  "currency": "USDT",
  "amount": "6.12",
  "expiration": 7200,
  "mchTradeNo": "testtesttesttesttesttesttesttest",
  "subject": "ThisIsOrderTitle",
  "body": "ThisIsOrderDesc",
  "notifyUrl": "https://fakepay.com/notifyTest",
  "successUrl": "https://fakepay.com/paySuccess.html",
  "extend": "123456",
  "reqTime": 1727702220747
}

请求参数

参数名 类型 必填 描述
chain String 是 主链
currency String 是 货币代码
amount String 是 订单金额（最多支持2位小数）
expiration Int 是 订单过期时间(单位秒)，最小300，最大10800
mchTradeNo String 是 商户生成的订单号，请确保唯一性
subject String 否 标题，禁止出现标点符号，特殊符号，可能影响商户交易成功率
body String 否 内容描述，禁止出现标点符号，特殊符号，可能影响商户交易成功率
notifyUrl String 否 我方通知商户接收交易结果地址，需返回SUCCESS确定接收成功，传值才会发起回调
successUrl String 否 客户在收银台付款成功后跳转url地址
extend String 否 扩展字段，自定义内容，在查询和回调时会返回，长度最大200
reqTime Int 是 请求接口时间,13位毫秒时间戳

返回示例

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "address": "TRuNJECgQ9uwGA4XSKuGC7xH6p7GUhwQTD",
    "chain": "TRX",
    "currency": "USDT",
    "mchTradeNo": "testtesttesttesttesttesttesttest",
    "payAmount": "6.123217",
    "payUrl": "https://pay.fakepay.com?tradeNo=BCI25032119029817377434296323027",
    "state": "PENDING",
    "totalAmount": "6.12",
    "tradeNo": "BCI25032119029817377434296323027"
  }
}

返回参数

参数名 类型 必传 描述
address String 是 收款地址
chain String 是 主链
currency String 是 货币代码
mchTradeNo String 是 商户生成的订单号
payAmount String 是 支付金额(客户需实际转账金额)
payUrl String 是 支付中间页(收银台链接,商户可嵌入自己的页面或跳转至新页面或根据参数自行实现收银台页面)
state String 是 订单状态
totalAmount String 是 订单总金额
tradeNo String 是 平台生成的订单号

查询代收订单

请求URL：/api/v1/blockchain/charge/query

请求方式：POST

请求类型：application/json

请求示例

{
    "tradeNo": "BCI25032119029817377434296323027",
    "mchTradeNo": "testtesttesttesttesttesttesttest",
    "reqTime": 1726295520933
}

请求参数

参数名 类型 必传 描述
tradeNo String 否 平台生成的订单号，与mchTradeNo二者传一即可,两者都传只认平台订单号
mchTradeNo String 否 商户生成的订单号，与tradeNo二者传一即可
reqTime long 是 请求接口时间,13位时间戳

返回示例

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "address": "TRuNJECgQ9uwGA4XSKuGC7xH6p7GUhwQTD",
    "chain": "TRX",
    "contractAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "currency": "USDT",
    "extend": "123456",
    "failDesc": "",
    "mchTradeNo": "testtesttesttesttesttesttesttest",
    "payAddress": "TRmbJzfKDpyKaeDPM8Yzft8q2PHTzRBbNG",
    "payAmount": "6.123217",
    "payChain": "TRX",
    "payCurrency": "USDT",
    "state": "SUCCESS",
    "successTime": 1741850325863,
    "totalAmount": "6.12",
    "tradeNo": "BCI25032119029817377434296323027",
    "txid": "2e54ec9bca399a5584065094d8a4dc24a92ffb2e7c8e81c16e598ba62c5d2b9e"
  }
}

返回参数

参数名 类型 必传 描述
address String 是 收款地址
chain String 是 主链
contractAddress String 否 合约地址
currency String 是 货币代码
extend String 是 扩展字段，自定义内容
failDesc String 否 失败原因
mchTradeNo String 是 商户生成的订单号
payAddress String 否 支付地址
payAmount String 是 需支付金额(客户需实际转账金额)
payChain String 否 支付链
payCurrency String 否 支付货币代码
state String 是 订单状态
successTime Int 否 成功时间
totalAmount String 是 订单总金额
tradeNo String 是 平台生成的订单号
txid String 否 链上唯一交易哈希

state字段说明:

state 描述
SUCCESS 支付成功
PENDING 交易创建，等待付款
REFUND 退款
FAIL 失败
EXPIRE 过期
CONFIRMING 收到付款等待交易确认成功和确认数达标
RELATED 已认领(金额不匹配的订单,此功能暂无)

代收通知

请求URL：该链接是通过统一下单接口提交的参数notifyUrl设置，如果无法访问链接，商户系统将无法接收到支付中心的通知。

请求方式：POST

请求类型：application/json

签名: header : PAY-SIGN

推送及时性: 默认及时,200 QPS

通知示例

{
  "address": "TMUuNPVRyMt4e3h7CU6RtFcb9DY1LrmuMQ",
  "chain": "TRX",
  "contractAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "currency": "USDT",
  "extend": "123456",
  "failDesc": "",
  "mchTradeNo": "TEST1234567891741849880",
  "payAddress": "TLRQZTR4tsUMPj3C3Gov5o3fuYPjRAmMZ1",
  "payAmount": "2.006369",
  "payChain": "TRX",
  "payCurrency": "USDT",
  "state": "SUCCESS",
  "successTime": 1741850325863,
  "totalAmount": "2",
  "tradeNo": "BCI25031319000822692934205448100275",
  "txid": "2e54ec9bca399a5584065094d8a4dc24a92ffb2e7c8e81c16e598ba62c5d2b9e"
}

通知参数

参数名 类型 必传 描述
address String 是 收款地址
chain String 是 主链
contractAddress String 否 合约地址
currency String 是 货币代码
extend String 是 扩展字段，自定义内容
failDesc String 否 失败原因
mchTradeNo String 是 商户生成的订单号
payAddress String 否 支付地址
payAmount String 是 需支付金额(客户需实际转账金额)
payChain String 否 支付链
payCurrency String 否 支付货币代码
state String 是 订单状态
successTime Int 否 成功时间
totalAmount String 是 订单总金额
tradeNo String 是 平台生成的订单号
txid String 否 链上唯一交易哈希

商户返回结果

需要对这整个 JSON 字符串进行签名验签 hmac(sha256, jsonString , secretKey) == header("PAY-SIGN")

state字段说明:

state 描述
SUCCESS 支付成功
PENDING 交易创建，等待付款
REFUND 退款
FAIL 失败
EXPIRE 过期
CONFIRMING 收到付款等待交易确认成功和确认数达标
RELATED 已认领(金额不匹配的订单,此功能暂无)

代付接口

代付下单

商户业务系统通过转账接口发起转账申请。

请求URL：/api/v1/blockchain/transfer

请求方式：POST

请求类型：application/json

请求示例

{
  "chain": "TRX",
  "currency": "USDT",
  "amount": "5",
  "address": "TPHdLs1qeAsGsfBqX4ghQRcz6vmNdm4d9m",
  "mchTradeNo": "testtesttesttesttesttesttesttest",
  "notifyUrl": "https://fakepay.com/notifyTest",
  "extend": "123456",
  "reqTime": 1726306060918
}

请求参数

参数名 类型 必填 描述
chain String 是 主链
currency String 是 货币代码
amount String 是 转账金额(最多2位小数)
address String 是 收款地址
mchTradeNo String 是 商户生成的转账订单号
notifyUrl String 否 回调地址
extend String 是 扩展字段，自定义内容，在查询和回调时会返回，长度最大200
reqTime Int 是 接口请求时间,13位毫秒时间戳

返回示例

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "address": "TPHdLs1qeAsGsfBqX4ghQRcz6vmNdm4d9m",
    "chain": "TRX",
    "contractAddress": "",
    "currency": "USDT",
    "extend": "123456",
    "failDesc": "",
    "mchTradeNo": "testtesttesttesttesttesttesttest",
    "payAddress": "",
    "payAmount": "5",
    "payChain": "",
    "payCurrency": "",
    "state": "PENDING",
    "successTime": 0,
    "totalAmount": "5",
    "tradeNo": "BCO25032119029819297041367041094",
    "txid": ""
  }
}

返回参数

参数名 类型 必传 描述
address String 是 收款地址
chain String 是 主链
contractAddress String 否 付款币种合约地址
currency String 是 货币代码
extend String 是 扩展字段，自定义内容
failDesc String 否 失败原因
mchTradeNo String 是 商户生成的订单号
payAddress String 否 付款地址
payAmount String 是 付款金额
payChain String 否 付款链
payCurrency String 否 付款货币代码
state String 是 订单状态
successTime Int 否 成功时间
totalAmount String 是 订单总金额
tradeNo String 是 平台生成的订单号
txid String 否 链上唯一交易哈希

查询代付订单

请求URL：/api/v1/blockchain/transfer/query

请求方式：POST

请求类型：application/json

请求示例

{
  "reqTime": 1726298455397,
  "tradeNo": "BCO25032119029819297041367041094",
  "mchTradeNo": "testtesttesttesttesttesttesttest"
}

请求参数

参数名 类型 必填 描述
tradeNo String 否 平台生成的代付单号，与mchTradeNo二者传一即可，都传时只认tradeNo
mchTradeNo String 否 商户生成的代付单号，与tradeNo二者传一即可
reqTime long 是 请求接口时间,13位时间戳

返回示例

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "address": "TPHdLs1qeAsGsfBqX4ghQRcz6vmNdm4d9m",
    "chain": "TRX",
    "contractAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "currency": "USDT",
    "extend": "123456",
    "failDesc": "",
    "mchTradeNo": "testtesttesttesttesttesttesttest",
    "payAddress": "TYyNHGCSzDkHzBSgqKACxjNVjytif7xYfG",
    "payAmount": "5",
    "payChain": "TRX",
    "payCurrency": "USDT",
    "state": "SUCCESS",
    "successTime": 1742541240154,
    "totalAmount": "5",
    "tradeNo": "BCO25032119029819297041367041094",
    "txid": "5d1126a341c1264dbb49c8e030c9ab296e1dd96c465ee58d6ad4d93d3e0f92b8"
  }
}

返回参数

参数名 类型 必传 描述
address String 是 收款地址
chain String 是 主链
contractAddress String 否 付款币种合约地址
currency String 是 货币代码
extend String 是 扩展字段，自定义内容
failDesc String 否 失败原因
mchTradeNo String 是 商户生成的订单号
payAddress String 否 付款地址
payAmount String 是 付款金额
payChain String 否 付款链
payCurrency String 否 付款货币代码
state String 是 订单状态
successTime Int 否 成功时间
totalAmount String 是 订单总金额
tradeNo String 是 平台生成的订单号
txid String 否 链上唯一交易哈希

state字段说明：

state 描述
SUCCESS 交易完成
PENDING 下单成功等待结算转账
CONFIRMING 已转出,等待交易确认和确认数达标
FAIL 转账执行失败(余额不足、账号无效等)

代付通知

请求URL：该链接是通过转账申请接口提交的参数notifyUrl设置，如果无法访问链接，商户系统将无法接收到支付中心的通知。

请求方式：POST

请求类型：application/json

签名： header: PAY-SIGN

推送及时性: 默认及时,200 QPS

通知示例数据

{
  "address": "TPHdLs1qeAsGsfBqX4ghQRcz6vmNdm4d9m",
  "chain": "TRX",
  "contractAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "currency": "USDT",
  "extend": "123456",
  "failDesc": "",
  "mchTradeNo": "testtesttesttesttesttesttesttest",
  "payAddress": "TYyNHGCSzDkHzBSgqKACxjNVjytif7xYfG",
  "payAmount": "5",
  "payChain": "TRX",
  "payCurrency": "USDT",
  "state": "SUCCESS",
  "successTime": 1742541240154,
  "totalAmount": "5",
  "tradeNo": "BCO25032119029819297041367041094",
  "txid": "5d1126a341c1264dbb49c8e030c9ab296e1dd96c465ee58d6ad4d93d3e0f92b8"
}

通知参数

参数名 类型 必传 描述
address String 是 收款地址
chain String 是 主链
contractAddress String 否 付款币种合约地址
currency String 是 货币代码
extend String 是 扩展字段，自定义内容
failDesc String 否 失败原因
mchTradeNo String 是 商户生成的订单号
payAddress String 否 付款地址
payAmount String 是 付款金额
payChain String 否 付款链
payCurrency String 否 付款货币代码
state String 是 订单状态
successTime Int 否 成功时间
totalAmount String 是 订单总金额
tradeNo String 是 平台生成的订单号
txid String 否 链上唯一交易哈希

state字段说明：

state 描述
SUCCESS 交易完成
PENDING 下单成功等待结算转账
CONFIRMING 已转出,等待交易确认和确认数达标
FAIL 转账执行失败(余额不足、账号无效等)

商户返回结果

需要对这整个 JSON 字符串进行签名验签 hmac(sha256, jsonString, secretKey) == header("PAY-SIGN")

沙箱支付

代收模拟支付

请求URL：/api/v1/sandbox/blockchain/charge/simulatePayment

请求方式：POST、GET

请求类型：application/json

请求示例

{
    "tradeNo": "BCI25032119029817377434296323027"
}

请求参数

参数名 类型 必填 描述
tradeNo String 是 系统订单号

返回示例

{
    "code": 200,
    "msg": "SUCCESS",
    "data": null
}

代付模拟支付成功

请求URL：/api/v1/sandbox/blockchain/transfer/simulatePayment

请求方式：POST、GET

请求类型：application/json

请求示例

{
    "tradeNo": "BCO25032119029819297041367041094"
}

请求参数

参数名 类型 必填 描述
tradeNo String 是 系统订单号

返回示例

{
    "code": 200,
    "msg": "SUCCESS",
    "data": null
}

代付模拟支付失败

请求URL：/api/v1/sandbox/blockchain/transfer/simulatePaymentFail

请求方式：POST、GET

请求类型：application/json

请求示例

{
    "tradeNo": "BCO25032119029819297041367041094"
}

请求参数

参数名 类型 必填 描述
tradeNo String 是 系统订单号

返回示例

{
    "code": 200,
    "msg": "SUCCESS",
    "data": null
}

接口状态码

The API uses the following error codes:

Code 提示 说明
200 SUCCESS 业务调用成功
400 Params error 参数异常
405 Invalid order no 业务条件不满足
429 Too many requests 请求过快
500 Internal service error 内部服务错误
1000 Merchant not exist or disabled 商户不存在或被禁用
1001 Invalid secret key 密钥错误
1002 IP is not on the whitelist ip不在白名单
1003 Order repeat 商户订单号重复
1004 Create order failed 订单创建失败
1005 Order not exist 订单不存在
1006 Insufficient Balance 余额不足
1007 The order is non refundable 订单不可退款
1008 The refund amount is not correct 退款金额不正确
1011 Invalid notify url 无效回调通知url
1012 No notify URL whitelist configured 没有配置通知url白名单
1013 Wallet is less or disabled 钱包被禁或不存在
1014 The account triggers the risk control rule 该账户触发风控规则
1016 Invalid amount 无效金额
1017 Invalid address 无效地址(地址格式错误)
1018 Invalid chain 无效主链
1019 Invalid currency 无效币种
1020 The current currency charge is suspended 暂停收款
1021 The current currency transfer is suspended 暂停出款
1022 Address not allocated, please contact customer service 未分配收款地址，请联系客服
1100 Invalid timestamp 请求头PAY-ACCESS-TIMESTAMP时间戳过期或为空,请传入当前UTC时区的13位毫秒时间戳数字,且该值要参与签名
1101 Invalid mchNo 请求头PAY-ACCESS-MCHNO无效商户号
1102 Invalid Content-Type 请求头Content-Type 请使用“application/JSON”格式
1103 Invalid signature 请求头PAY-ACCESS-SIGN无效签名
2004 System error, please contact customer service 系统错误，请联系客服