交易报文

原生支付

交易类型： 后台交易

统一提交地址（除收银台支付外）：https://openapi.basicex.com/basicexpay/trade/gateway

请求方式：POST

Content-Type：application/json

注：推荐采用收银台支付(basicexpay.trade.cashier)接口进行支付订单提交；

如采用原生支付方式，请采用交易预创建(basicexpay.trade.precreate)接口进行提交（仅支持币趣多端支付）。

收银台支付(basicexpay.trade.cashier)

交易类型： 前台交易

收银台交易为前台交易，采用表单提交的方式上送交易

请求方式：POST

Content-Type：application/x-www-form-urlencoded

提交地址： https://openapi.basicex.com/basicexpay/trade/cashier

表单提交上送参数名称固定为“data”，参数值为商户后台按公共参数及请求参数说明完成签名后组装的 json 串。表单自动提交页面样例如下：

<form id="cashier" method="post" contentType="application/x-www-form-urlencoded;charset=utf-8" action="https://openapi.basicex.com/basicexpay/trade/cashier">
	<input type="hidden" name="data" id="data" value="{"merNo":"811496833912834","method":"basicexpay.trade.cashier","timestamp":"20230221155554","nonce":"PIYuG0gFpMhGaDIU","bizConent":"{\"merOrderNo\":\"lZUJVCNLfhlaH1ZzEHIrjszT\",\"clientIp\":\"192.168.1.2\",\"totalAmount\":100,\"currency\":\"USDT\",\"description\":\"TopUp\",\"orderSource\":\"WEB\",\"tradeStartTime\":\"2023-02-21 15:55:54\",\"expireTime\":900,\"notifyUrl\":\"https://www.test.com\",\"returnUrl\":\"https://www.test.com\",\"attach\":\"123\",\"goodsDetails\":[{\"goodsType\":\"112\",\"goodsId\":\"12\",\"goodsName\":\"TopUp\",\"quantity\":1,\"price\":100}]}","signType":"HmacSHA512","sign":"0AF6A4113EC32E9F4A69B62B8842D25AEA7B8C91B260FE98CCF8CEB622F19F1601A4A402999EE2A45CB78B1E8C1961DE4591B3273CB99A85DF5C46DE21B35476"}"/>
</form>
<script>document.forms['cashier'].submit();</script>

请求参数说明

注意: 该请求参数顺序需按照以下表格顺序进行排列

参数	类型	必填	参数说明	样例
merOrderNo	string(32)	是	商户订单号，商户系统内部支付订单号，只能是数字、大小写字母，且在同一个商户号下唯一	202202161004008765432
clientIp	string(20)	是	客户端 IP,提交订单的客户端设备 IP	192.168.1.12
totalAmount	decimal(12,2)	是	订单总金额， 精确到小数点后两位	200
currency	string(100)	是	币种 ，支持 USDT,BCNY	USDT
description	string(255)	是	商品描述 ，可能会展示在收银台上，请规范填写	话费充值
orderSource	string(10)	是	订单来源，APP/WEB/WAP/OTHERS	WEB
tradeStartTime	string(19)	是	交易发起时间, 19 位长度,格式:yyyy-MM-dd HH:mm:ss	2022-02-16 10:04:00
expireTime	string(4)	否	订单有效期，固定值900,单位为秒	900
notifyUrl	string(255)	否	后台通知地址，异步接收支付结果通知的回调地址，必须为外网可访问的 URL	https://api.xxx.com/cashier/notify
returnUrl	string(255)	否	前台跳转地址，支付完成后，从收银台跳回商户商城页面的地址，必须为外网可访问的 URL	https://api.xxx.com/cashier/redirect
attach	string(100)	否	附加数据，原样返回
**+**goodsDetails		否	商品详情（如填写此项，以下均需填写）
└ goodsType	string(8)	是	商品类别	2101
└ goodsId	string(50)	是	商品编号	1001121
└ goodsName	string(100)	是	商品名称	话费充值
└ quantity	int(10)	是	商品数量	1
└ price	string(12)	是	商品单价，精确到小数点后两位	200

请求报文样例

{
  "merOrderNo": "swR75kHGS2jQYfeN",
  "clientIp": "127.0.0.1",
  "totalAmount": 18.37,
  "currency": "USDT",
  "description": "会员充值",
  "orderSource": "APP",
  "tradeStartTime": "2023-03-31 22:03:53",
  "expireTime": 900,
  "notifyUrl": "https://google.com",
  "returnUrl": "https://google.com",
  "attach": "",
  "goodsDetails": [
    {
      "goodsType": "01",
      "goodsId": "100001",
      "goodsName": "Test",
      "quantity": 1,
      "price": 18.37
    }
  ]
}

应答参数说明

前端 form 表单形式提交参数后，页面自动跳转到币趣收银台页面。

交易预创建(basicexpay.trade.precreate)

交易类型： 后台交易

请求参数说明

注意: 该请求参数顺序需按照以下表格顺序进行排列

参数	类型	必填	参数说明	样例
merOrderNo	string(32)	是	商户订单号，商户系统内部支付订单号，只能是数字、大小写字母，且在同一个商户号下唯一	202202161004008765432
clientIp	string(20)	是	客户端 IP,提交订单的客户端设备 IP	192.168.1.12
totalAmount	decimal(12,2)	是	订单总金额， 精确到小数点后两位	200
currency	string(20)	是	币种 ，支持 USDT、BCNY	USDT
network	string(20)	否	转账网络，支持 ERC20、TRC20、POLYGON、BSC，外部充值时必传	TRC20
description	string(255)	是	商品描述 ，可能会展示在收银台上，请规范填写	话费充值
orderSource	string(10)	是	订单来源，APP/WEB/WAP/OTHERS	WEB
tradeStartTime	string(19)	是	交易发起时间, 19 位长度,格式:yyyy-MM-dd HH:mm:ss	2022-02-16 10:04:00
expireTime	string(4)	否	订单有效期，固定值900,单位为秒	900
notifyUrl	string(255)	否	后台通知地址，异步接收支付结果通知的回调地址，必须为外网可访问的 URL	https://api.xxx.com/cashier/notify
returnUrl	string(255)	否	前台跳转地址，支付完成后，从收银台跳回商户商城页面的地址，必须为外网可访问的 URL	https://api.xxx.com/cashier/redirect
attach	string(100)	否	附加数据，原样返回
network	string(20)	否	转账网络，支持 ERC20、TRC20、POLYGON、BSC，外部充值时必传	TRC20
**+**goodsDetails		否	商品详情（如填写此项，以下均需填写）
└ goodsType	string(8)	是	商品类别	2101
└ goodsId	string(50)	是	商品编号	1001121
└ goodsName	string(100)	是	商品名称	话费充值
└ quantity	int(10)	是	商品数量	1
└ price	string(12)	是	商品单价，精确到小数点后两位	200

请求报文样例

{
  "merOrderNo": "swR75kHGS2jQYfeN",
  "clientIp": "127.0.0.1",
  "totalAmount": 18.37,
  "currency": "USDT",
  "description": "会员充值",
  "orderSource": "APP",
  "tradeStartTime": "2023-03-31 22:03:53",
  "expireTime": 900,
  "notifyUrl": "https://google.com",
  "returnUrl": "https://google.com",
  "attach": "",
  "goodsDetails": [
    {
      "goodsType": "01",
      "goodsId": "100001",
      "goodsName": "Test",
      "quantity": 1,
      "price": 18.37
    }
  ]
}

应答参数说明

参数	类型	必填	参数说明	样例
orderNo	string(32)	是	系统订单号，币趣支付生成的唯一订单号	202201261004008765432
merOrderNo	string(32)	是	商户系统内部支付订单号,同请求参数	202201261004008765432
totalAmount	decimal(12,2)	是	订单总金额， 精确到小数点后两位,同请求参数	200
currency	string(20)	是	币种，支持 USDT,BCNY，同请求参数	USDT
network	string(20)	否	转账网络，同请求参数	TRC20
orderSource	string(10)	是	订单来源,同请求参数	WEB
codeUrl	string(255)	是	支付二维码数据，以二维码形式展示给用户扫码支付	https://qr.basicex.com/811496833912834/C1E988EBCE9EA8DD2CC3A99AB9354EF3
attach	string(100)	否	附加数据,同请求参数

交易结果查询(basicexpay.trade.query)

交易类型： 后台交易

请求参数说明

注意: 该请求参数顺序需按照以下表格顺序进行排列

参数	类型	必填	参数说明	样例
merOrderNo	string(32)	否	商户订单号，商户系统内部支付订单号,与系统订单号 orderNo 不能同时为空	202202161004008765432
orderNo	string(32)	否	系统订单号，币趣支付生成的唯一订单号，与商户订单号 merOrderNo 不能同时为空	202202161004008765431

请求报文样例

{
    "merOrderNo": "202202161004008765432"
}

应答参数说明

参数	类型	必填	参数说明	样例
orderNo	string(32)	是	系统订单号，币趣支付生成的唯一订单号,同交易创建请求参数	202201261004008765432
merOrderNo	string(32)	是	商户系统内部支付订单号,同交易创建请求参数	202201261004008765432
totalAmount	decimal(12,2)	是	订单总金额， 精确到小数点后两位,同交易创建请求参数	200
currency	string(20)	是	币种，支持 USDT,BCNY，同交易创建请求参数	USDT
status	string(2)	是	交易状态 0:等待用户支付 1:处理中 2:交易成功 3:已过期 4:交易失败	2
tradeFinishTime	string(19)	是	交易完成时间	2022-02-13 16:29:07
transactionId	string(60)	否	交易订单号	202201261004008765432
buyerid	string(50)	否	付款人标识
attach	string(100)	否	附加数据,同交易创建请求参数

退款(basicexpay.trade.refund)

交易类型： 后台交易

请求参数说明

注意: 该请求参数顺序需按照以下表格顺序进行排列

参数	类型	必填	参数说明	样例
merOrderNo	string(32)	否	商户订单号，商户系统内部支付订单号,与系统订单号 orderNo 不能同时为空	202202161004008765432
orderNo	string(32)	否	系统订单号，币趣支付生成的唯一订单号，与商户订单号 merOrderNo 不能同时为空	202202161004008765431
merRefundOrderNo	string(32)	是	商户退款订单号	202202161004008765435
refundAmount	decimal(12,2)	是	退款金额	100
refundReason	string(100)	是	退款原因	退货
tradeStartTime	string(19)	是	交易发起时间，19 位长度,格式:yyyy-MM-dd HH:mm:ss	2022-02-13 16:29:07

请求报文样例

{
    "merOrderNo": "202202161004008765432",
    "merRefundOrderNo": "202202161004008765123",
    "refundAmount": 100,
    "refundReason": "退货",
    "refundReason": "2022-02-13 16:29:07"
}

应答参数说明

参数	类型	必填	参数说明	样例
orderNo	String(32)	否	系统订单号，币趣支付生成的唯一订单号,同请求参数	202201261004008765432
merOrderNo	String(32)	否	商户系统内部支付订单号,同请求参数	202201261004008765431
merRefundOrderNo	string(32)	是	商户退款订单号	202201261004008765436
refundOrderNo	string(32)	是	系统退款订单号	202201261004008765435
refundAmount	decimal(12,2)	是	退款金额， 精确到小数点后两位,同请求参数	100
refundStatus	string(2)	是	退款状态 0:退款中 1:审批中 2:退款成功 3:退款失败	2

退款结果查询(basicexpay.trade.refund.query)

交易类型： 后台交易

请求参数说明

注意: 该请求参数顺序需按照以下表格顺序进行排列

参数	类型	必填	参数说明	样例
merRefundOrderNo	string(32)	否	退款商户订单号，商户系统内部支付订单号,与退款系统订单号 orderNo 不能同时为空	202202161004008765432
refundOrderNo	string(32)	否	退款系统订单号，币趣支付生成的唯一订单号，与退款商户订单号 merOrderNo 不能同时为空	202202161004008765431

请求报文样例

{
    "merRefundOrderNo": "202202161004008765432"
}

应答参数说明

参数	类型	必填	参数说明	样例
refundOrderNo	string(32)	是	系统退款订单号，币趣支付生成的唯一订单号,同交易创建请求参数	202201261004008765432
merRefundOrderNo	string(32)	是	商户退款订单号，商户系统内部退款订单号,同交易创建请求参数	202201261004008765432
refundAmount	decimal(12,2)	是	退款金额， 精确到小数点后两位,同交易创建请求参数	200
status	string(2)	是	交易状态 0:退款中 1:审批中 2:退款成功 3:退款失败	2
tradeFinishTime	string(19)	是	交易完成时间	2022-02-13 16:29:07
transactionId	string(60)	否	交易流水号	202201261004008765432
attach	string(100)	否	附加数据,同交易创建请求参数

代付(basicexpay.trade.agentpay)

交易类型： 后台交易

代付交易是币趣支付为解决商户资金出款需求，提供将商户币趣账户资金付款到指定币趣钱包或指定区块链钱包地址的资金结算服务。

币趣钱包指通过币趣钱包官网注册得个人或者企业用户，币趣支付都会为其创建币趣钱包，币趣钱包现金账户可相互转账，不同币种资金相互独立。同一邮箱地址、手机号、币趣 ID、用户名可唯一确定一个币趣钱包。代付请求通过指定代付对象类型（targetType）和代付对象（target）来确定收款钱包。

区块链钱包地址，币趣支付支持 TRC20、ERC20、POLYGON、BSC 等网络的钱包地址的代付请求。当需要代付到区块链钱包地址时，代付对象类型（targetType）必须设置成"ADDRESS"，代付对象（target）则为具体区块链钱包地址。

当应答报文中交易状态（status）为失败时，该订单失败，商户可重新发起；

当应答报文中交易状态（status）为处理中时候，商户可单独调用【代付结果查询】接口，进行订单状态的查询；

发起代付交易前，请确认商户现金账户资金是否充足，减少交易失败几率。

请求参数说明

注意: 该请求参数顺序需按照以下表格顺序进行排列

参数	类型	必填	参数说明	样例
merOrderNo	string(32)	是	商户订单号，商户系统内部支付订单号，且在同一个商户号下唯一	202202161004008765432
clientIp	string(32)	否	客户端 IP,提交订单的客户端设备 IP	192.168.1.12
targetType	string(12)	是	代付对象类型，可传 EMAIL、TELEPHONE、BEID、USERID、ADDRESS	EMAIL
target	string(64)	是	代付对象[target] 不可为空，可传 email、手机号、币趣 id、用户名、地址	[email protected]
totalAmount	decimal(12,2)	是	订单总金额， 精确到小数点后两位	100
currency	string(50)	是	币种 ，支持 USDT,BUSD,BCNY	USDT
network	string(50)	否	网络，支持 TRC20、ERC20、POLYGON、BSC，当 targetType 为 ADDRESS 时必传	TRC20
description	string(255)	是	代付描述	工资
orderSource	string(10)	是	订单来源，APP/WEB/WAP/OTHERS	WEB
tradeStartTime	string(19)	是	交易发起时间, 19 位长度,格式:yyyy-MM-dd HH:mm:ss	2022-02-13 16:29:07
notifyUrl	string(255)	否	代付结果通知地址，异步接收代付结果通知的回调地址，必须为外网可访问的 URL	https://api.xxx.com/cashier/notify
attach	string(100)	否	附加数据，原样返回

请求报文样例

{
  "merOrderNo": "drZW6FffaGpit7Db",
  "clientIp": "127.0.0.1",
  "targetType": "EMAIL",
  "target": "[email protected]",
  "totalAmount": 33.53,
  "currency": "USDT",
  "network": "TRC20",
  "description": "工资",
  "orderSource": "APP",
  "tradeStartTime": "2023-03-31 22:27:46",
  "notifyUrl": "https://api.xxx.com/cashier/notify",
  "attach": ""
}

应答参数说明

参数	类型	必填	参数说明	样例
orderNo	String(32)	是	系统订单号，币趣支付生成的唯一订单号,同交易创建请求参数	202201261004008765432
merOrderNo	String(32)	是	商户系统内部支付订单号,同交易创建请求参数	202201261004008765432
totalAmount	Decimal(12,2)	是	订单总金额， 精确到小数点后两位,同交易创建请求参数	200
currency	String(20)	是	币种，支持 USDT,BCNY，同交易创建请求参数	USDT
orderSource	string(10)	是	订单来源，APP/WEB/WAP/OTHERS	WEB
status	String(2)	是	交易状态 0:处理中 1:交易成功 2:交易失败	1
attach	String(100)	否	附加数据,同交易创建请求参数

代付结果查询(basicexpay.trade.agentpay.query )

交易类型： 后台交易

请求参数说明

注意: 该请求参数顺序需按照以下表格顺序进行排列

参数	类型	必填	参数说明	样例
merOrderNo	string(32)	否	商户代付订单号，商户系统内部代付订单号,与系统订单号 orderNo 不能同时为空	202202161004008765432
orderNo	string(32)	否	系统代付订单号，币趣支付生成的唯一订单号，与商户代付订单号 merOrderNo 不能同时为空	202202161004008765431

请求报文样例

{
    "merOrderNo": "202202161004008765432"
}

应答参数说明

参数	类型	必填	参数说明	样例
merOrderNo	string(32)	是	商户系统内部支付订单号,同交易请求参数	202201261004008765431
orderNo	string(32)	是	系统订单号，币趣支付生成的唯一订单号,同交易请求参数	202201261004008765432
targetType	string(12)	是	代付对象类型,同交易请求参数	EMAIL
target	string(64)	是	代付对象,同交易请求参数	[email protected]
totalAmount	decimal(12,2)	是	订单总金额， 精确到小数点后两位,同交易请求参数	200
currency	string(20)	是	币种，支持 USDT,BCNY，同交易请求参数	USDT
network	string(50)	否	网络，同交易请求参数	TRC20
description	string(19)	是	代付描述 ，同交易请求参数	工资
orderSource	string(60)	否	订单来源，同交易请求参数	WEB
attach	string(100)	否	附加数据,同交易创建请求参数
status	string(2)	是	交易状态 0:处理中 1:交易成功 2:交易失败	2
tradeFinishTime	string(19)	是	交易完成时间	2022-02-13 16:29:07
transactionId	string(60)	否	交易流水号	202201261004008765432

汇率查询(basicexpay.exchange.rate.query)

交易类型： 后台交易

请求参数说明

注意: 该请求参数顺序需按照以下表格顺序进行排列

参数	类型	必填	参数说明	样例
source	string(10)	是	源币种，支持 USDT,BCNY	USDT
target	string(10)	是	目标币种，支持 CNY、EUR、HKD、INR、PHP、Rp、THB、USD、MXN	CNY

请求报文样例

{
    "source": "USDT",
    "target": "CNY"
}

应答参数说明

参数	类型	必填	参数说明	样例
source	string(10)	是	源币种，支持 USDT,BCNY，同请求参数	USDT
target	string(10)	是	目标币种，同请求参数	CNY
rate	decimal(16,2)	是	汇率，指单位币种的兑换汇率,1USDT=6.96CNY	6.96