API开发接口文档

本文档主要描述商户接入平台涉及到的对接标准与技术细节，请开发同学仔细阅读对接规范，便于快速接入，谢谢！

如你在接入过程中遇到任何问题，可随时联系在线客服获得技术支持。

获取商户UID

商户UID指的是用户在平台注册后，分配给用户的一个6位数唯一编码，代表着用户在平台中的唯一身份，请妥善保管。

生成商户密钥

商户在接入平台时要使用到的秘钥，秘钥主要用于验签,安全访问。密钥在商户管理后台-->API接入中查看。

请求示例和验签说明

请求方式：POST

Content-type：application/json

为了保证传递的数据不被修改，所有接口请求和回调都需要进行摘要认证。

请求参数

以下为请求的最外层参数，每个接口的专用参数请转成json格式后放入data字段中

字段名称 字段类型 是否必填 说明
uid string 是 UID
timestamp string 是 时间戳
sign string 是 签名
data string 是 json字符串，具体见对应的接口说明

请求示例：

{
    "uid": "136994",
    "sign": "00bd24ca1fa29a333191235aad10621a",
    "timestamp": "1716700031",
    "data": "{\"Amount\":\"2\",\"Blockchain\":\"TRC20\",\"CustomerOrderNo\":\"TEST127\",\"EffectiveDuration\":300,\"JumpURL\":\"111\"}"
}

签名方式

sign=md5(uid + data + key + timestamp)，其中key为商户密钥

签名代码PHP示例：

$uid = "136994";
$data = '{"Amount":"2","Blockchain":"TRC20","CustomerOrderNo":"TEST127","EffectiveDuration":300,"JumpURL":"111"}';
$time = "1716700031";
$key = "c6e86d12aa021a3a94ea45235ca5d9aa";
$sign = md5($uid . $data . $key . $time);
echo $sign;//2a81cd6c131f4c1ac88c2f9408000470

返回结果

以下为返回结果的最外层参数

字段名称 字段类型 是否必填 说明
code int 是 返回码
msg string 是 返回码描述
data string 是 具体的返回结果，见对应的接口说明

返回示例：

{
	"code": 200,
	"data": {
		"MerchantSellOrderStatus": "T_MERCHANT_VERIFY_TODO",
		"MerchantSellOrderStatusText": "待商户审核"
	},
	"msg": "success"
}

发起收款

请求地址：域名/Open.Customer/CreateReceiveOrder

请求参数：

字段名称 字段类型 是否必填 说明
Amount string 是 收款订单金额(USDT),预留4位小数,实际使用2位小数
Blockchain string 是 链路类型,目前只支持TRC20
CustomerOrderNo string 是 客户订单号
EffectiveDuration string 是 订单有效期,300-86400之间,单位秒
JumpURL string 否 商户会员支付成功后,收银界面上返回按钮对应的链接
Rule Object 否 当前订单执行的规则,不传则按商户默认配置执行,具体见示例

接口请求示例：

{
    "uid": "136994",
    "sign": "33748c41adaa6ee11a8e863d1fe9f250",
    "timestamp": "1716700031",
    "data": "{\"Amount\":\"33\",\"Blockchain\":\"TRC20\",\"CustomerOrderNo\":\"TEST156\",\"EffectiveDuration\":300,\"JumpURL\":\"111\",\"Rule\":{\"WalletRules\":{\"Range\":\"SpecifyWallet\",\"Order\":\"Loop\",\"AutoCreate\":\"Off\",\"Register\":\"Register\",\"SpecifyWalletAddress\":\"TVEZobKr3Fyj6dayBcpSpoDLfb3B63Xj7b\"},\"AmountRules\":{\"Floor\":\"Off\"},\"CollectRules\":{\"AutoCollect\":\"On\",\"ToAddress\":\"TVEZobKr3Fyj6dayBcpSpoDLfb3B63Xj7b\",\"Frequency\":\"0\"}}}"
}
//Rule Example
$rule = [
    'WalletRules'=>[
        'Range'=>'AllWallets',//钱包范围,AllWallets,AllSystemWallets,CreateNewSystemWallet,CreateDisposableSystemWallet,SpecifyWallet
        'Order'=>'Loop',//钱包收款排序,Loop,BalanceAsc,BalanceDesc
        'AutoCreate'=>'On',//自动生成钱包,On,Off
        'Register'=>'Register',//钱包激活规则,DoNotRegister,Register,RegisterAndTransferU
        'SpecifyWalletAddress'=>'',//指定钱包地址,仅当Range=SpecifyWallet时有效
    ],
    'AmountRules'=>[
        'Floor'=>'Off',//匹配时先对金额进行floor操作,On,Off
    ],
    'CollectRules'=>[
        'AutoCollect'=>'On',//是否开启,On,Off
        'ToAddress'=>'Txxxxxx',//归集地址,未添加为钱包的会自动添加
        'Frequency'=>'0',//归集频率,注意格式为字符串,0(表示收到后立即归集),1,4,24
    ],
    'RiskRules'=>[
        'NeedToConfirm'=>'On',//付款地址存在风险时需要手动确认,是否开启,On,Off
    ],
];

接口返回：

字段名称 字段类型 是否必填 说明
CheckOutUrl string 是 下单成功后返回的收银台URL地址,商户会员付款页面
ReceiveAddress string 是 订单对应的收款地址

接口返回示例：

{
    "CheckOutUrl": "http://localhost:8000/Open.Customer/CheckOut?data=Ergz52xOPB9SJKW0CqbajDRPJIihDDCO8IYwIdR8MZgRAiOthgnK%2BsBjPQ7SBVqvYNuudqrYQlRDvlD4epD1QMeRp5wQlHRhugTbYCvJF3M%3D",
    "ReceiveAddress": "TLvT5GG3aWiTknCvGbux2CW6wgwznogBF2",
    "code": 0,
    "msg": "success"
}

收款订单状态查询

请求地址：域名/Open.Customer/GetReceiveOrderStatus

请求参数：

字段名称 字段类型 是否必填 说明
CustomerOrderNo string 是 商户订单编号,即你自己系统里的订单编号,便于后续对账

接口请求示例：

{
    "uid": "136994",
    "sign": "00bd24ca1fa29a333191235aad10621a",
    "timestamp": "1716700031",
    "data": "{\"CustomerOrderNo\":\"126\"}"
}

接口返回：

字段名称 字段类型 是否必填 说明
UID string 是 商户UID
OrderNo string 是 系统订单号
CustomerOrderNo string 是 商户订单号
Status string 是 订单状态,详见文档底部收款订单状态码
FinishTime string 是 订单完成时间,如果未完成则返回Null
Amount string 是 订单金额(USDT),预留4位小数,实际使用2位小数
AmountInFact string 是 订单实收金额,如果未完成则返回Null

接口返回示例：

{
    "ReceiveOrder": {
        "UID": "136994",
        "OrderNo": "SK2405252026240048",
        "CustomerOrderNo": "126",
        "Status": "待付款",
        "FinishTime": null,
        "Amount": "1.0000",
        "AmountInFact": null
    },
    "code": 0,
    "msg": "success"
}

收款回调

当订单完成或补单完成时会进行回调。回调会最多进行3次,成功接收回调需返回'success'。请求方式为POST,Content-Type: application/json

请求地址：在商户后台->API接入中设置

请求参数：

字段名称 字段类型 是否必填 说明
OrderType string 是 订单类型,收款回调时固定为ReceiveOrder
ReceiveOrder.UID string 是 商户UID
ReceiveOrder.OrderNo string 是 系统订单号
ReceiveOrder.CustomerOrderNo string 是 商户订单号
ReceiveOrder.Status string 是 订单状态,详见文档底部收款订单状态码
ReceiveOrder.FinishTime string 是 订单完成时间
ReceiveOrder.Amount string 是 订单金额(USDT),预留4位小数,实际使用2位小数
ReceiveOrder.AmountInFact string 是 订单实收金额
ReceiveOrder.Txid string 是 订单交易哈希

接口请求示例：

{
    "uid":136994,
    "timestamp":1716720904,
    "data":"{\"OrderType\":\"ReceiveOrder\",\"ReceiveOrder\":{\"UID\":\"136994\",\"OrderNo\":\"SK2405251145300005\",\"CustomerOrderNo\":\"122\",\"Status\":\"已完成\",\"FinishTime\":\"2024-05-25 17:27:28\",\"Amount\":\"1.0000\",\"AmountInFact\":\"1.0000\"}}",
    "sign":"90de05574c1630b4d11a94a32cd0bad6"
}

发起付款

请求地址：域名/Open.Customer/CreatePaymentOrder

请求参数：

字段名称 字段类型 是否必填 说明
Amount string 是 付款金额(USDT),预留4位小数,实际使用2位小数
CustomerOrderNo string 是 商户订单编号,即你自己系统里的订单编号,便于后续对账
Blockchain string 是 链路类型,目前只支持TRC20
FromAddress string 是 发起地址,填写具体地址或AUTO,AUTO表示自动匹配
ToAddress string 是 接收地址

接口请求示例：

{
    "uid": "136994",
    "sign": "00bd24ca1fa29a333191235aad10621a",
    "timestamp": "1716700031",
    "data": "{\"Amount\":\"1\",\"Blockchain\":\"TRC20\",\"CustomerOrderNo\":\"127\",\"FromAddress\":\"TMQvgsJLGRh48sth9wgFN4Xptgs6TFkAbd\",\"ToAddress\":\"TSVAFSHBBsEHB6UbCn7ogUmZhjSpvHdPQN\"}"
}

接口返回示例：

{
    "PaymentOrder": {
        "OrderNo": "FK2405261145180046",
        "CustomerOrderNo": "127",
        "FromAddress": "TMQvgsJLGRh48sth9wgFN4Xptgs6TFkAbd"
    },
    "code": 0,
    "msg": "success"
}

付款订单状态查询

请求地址：域名/Open.Customer/GetPaymentOrderStatus

请求参数：

字段名称 字段类型 是否必填 说明
UID string 是 商户UID
OrderNo string 是 系统订单号
CustomerOrderNo string 是 商户订单号
Status string 是 订单状态,详见文档底部付款订单状态码
FinishTime string 是 订单完成时间,如果未完成则返回Null
Amount string 是 订单金额(USDT),预留4位小数,实际使用2位小数

接口请求示例：

{
    "uid": "136994",
    "sign": "00bd24ca1fa29a333191235aad10621a",
    "timestamp": "1716700031",
    "data": "{\"CustomerOrderNo\":\"FK2405211522064632\"}"
}

接口返回示例：

{
    "PaymentOrder": {
        "UID": "136994",
        "OrderNo": "FK2405211522064632",
        "CustomerOrderNo": "FK2405211522064632",
        "Status": "付款中",
        "Amount": "123.0000",
        "FinishTime": null
    },
    "code": 0,
    "msg": "success"
}

付款回调

当订单完成时会进行回调。回调会最多进行3次,成功接收回调需返回'success'。请求方式为POST,Content-Type: application/json

请求地址：在商户后台->API接入中设置

请求参数：

字段名称 字段类型 是否必填 说明
OrderType string 是 订单类型,付款回调时固定为PaymentOrder
PaymentOrder.UID string 是 商户UID
PaymentOrder.OrderNo string 是 系统订单号
PaymentOrder.CustomerOrderNo string 是 商户订单号
PaymentOrder.Status string 是 订单状态,详见文档底部收款订单状态码
PaymentOrder.FinishTime string 是 订单完成时间
PaymentOrder.Amount string 是 订单金额(USDT),预留4位小数,实际使用2位小数
PaymentOrder.Txid string 是 订单交易哈希

接口请求示例：

{
    "uid": "136994",
    "timestamp": 1716721664,
    "data": "{\"OrderType\":\"PaymentOrder\",\"PaymentOrder\":{\"UID\":\"136994\",\"OrderNo\":\"FK2405261145180046\",\"CustomerOrderNo\":\"127\",\"Status\":\"付款中\",\"FinishTime\":null,\"Amount\":\"1.0000\"}}",
    "sign": "153902d63b413837012d65a6a18e3461"
}

预付账户余额查询

请求地址：域名/Open.Customer/GetAdvanceAccountBalance

请求参数：

字段名称 字段类型 是否必填 说明

接口请求示例：

{
    "uid": "136994",
    "sign": "00bd24ca1fa29a333191235aad10621a",
    "timestamp": "1716700031",
    "data": "{}"
}

接口返回：

字段名称 字段类型 是否必填 说明
Balance string 是 账户余额

接口返回示例：

{
    "AdvanceAccount": {
        "Balance": "2.8222"
    },
    "code": 0,
    "msg": "success"
}

钱包余额查询

请求地址：域名/Open.Customer/GetWalletBalance

请求参数：

字段名称 字段类型 是否必填 说明

接口请求示例：

{
    "uid": "136994",
    "sign": "00bd24ca1fa29a333191235aad10621a",
    "timestamp": "1716700031",
    "data": "{\"Address\":\"TASz7np3asoQiUi9eG8F9TXPyrXYmTJtqg\"}"
}

接口返回：

字段名称 字段类型 是否必填 说明
Balance string 是 账户余额

接口返回示例：

{
    "Wallet": {
        "Balance": "2.8222"
    },
    "code": 0,
    "msg": "success"
}

创建独享收款地址

请求地址：域名/Open.Customer/CreateWalletForSpecifiedUser

请求参数：

字段名称 字段类型 是否必填 说明
SpecifiedUserID string 否 需要绑定的用户ID,非必填

接口请求示例：

{
    "uid": "136994",
    "sign": "00bd24ca1fa29a333191235aad10621a",
    "timestamp": "1716700031",
    "data": "{\"SpecifiedUserID\":\"5\"}"
}

接口返回：

字段名称 字段类型 是否必填 说明
Balance string 是 账户余额

接口返回示例：

{
    "Wallet": {
        "Address": "TASz7np3asoQiUi9eG8F9TXPyrXYmTJtqg",
        "SpecifiedUserID": "123",
        "Blockchain": "TRC20",
    },
    "code": 0,
    "msg": "success"
}

返回码

返回码 描述
0 请求成功
403 认证失败或无权操作,具体信息见返回的msg字段
404 未找到相关信息,具体信息见返回的msg字段
-1 其他错误,具体信息见返回的msg字段

收款订单状态码

状态码 描述
待付款 待付款
已完成 已完成
补单已完成 补单已完成(也视作完成)
付款超时 付款超时
付款风险 付款风险

付款订单状态码

状态码 描述
付款中 付款中
已完成 已完成
待付款 待付款

demo下载

php_demo.zip