三方支付 API 文档（TRON TRX/USDT）Ver 1.86

面向开发者的接口规范文档，包含鉴权、收款、付款、异步通知与查询接口。

API域名：https://api.tronspay.com 格式：POST + application/json

1. 鉴权说明

接入前请先联系商务开通商户账户，在商户管理中获取 merchantId 与签名 Key。

每个请求必须在 Header 中传入 token、sign、merchantId。

  • token：时间戳
  • merchantId：商户编号
  • sign：小写 md5(请求体 + token + 签名Key)
https://api.tronspay.com
POST
application/json
UTF-8

建议服务端校验 token 时效（如 5 分钟）并记录签名日志，防止重放攻击与请求伪造。

签名示例
requestBody = "{\"orderNo\":\"122558566332\",\"asset\":\"Usdt\"}"

token = "1734029562000"
key = "merchant-sign-key"
sign = md5(requestBody + token + key).toLowerCase()
成功响应示例
{
    "code": 1, 
    "msg": "操作成功",
    "data": {}
}

返回字段说明

状态码 0 失败 1成功 1001签名错误
返回消息

2. 创建收款订单

/api/Thrpay/inOrder

根据参数创建收款订单，平台给出收银台地址，引导客户完成支付后，通知您到到帐成功。

请求参数

是，商户订单号，必须唯一
是，Trx|Usdt
是，最多 3 位小数
否，到账回调 URL
  • 订单号重复会返回重复数据并创单失败。
  • 请求成功后需要前端跳转收银台URL(返回字段中的cashier即为收银台)，引导客户完成支付。
请求示例
{
  "orderNo": "122558566332",
  "asset": "Usdt",
  "money": "20.53",
  "call_url": "https://merchant.example.com/callback/in"
}
成功响应示例
{
    "code": 1, 
    "msg": "操作成功",
    "data":
            {
                "Id": "5678690426168186944",
                "OrderNo": "505910570909777408",
                "MerchantId": "1650155505404",
                "MerchantName": "测试商户",
                "Asset": "Usdt",
                "ToAddress": "TKUVtbilLu2Ma……cXN2Ke888",
                "Money": 25.0,
                "Fee": 1.0,
                "State": 1,
                "CreateTime": "2025-08-01 14:13:56",
                "Cashier": "https://x.x.com/x.html?id=2" 
            }
}

返回字段说明

我方平台订单号
商户订单号
商户编号
商户名称
币种
接收地址
订单金额
手续费
是否手动认领
状态：1待存款；2已到账；4已超时；5无效订单
订单建立时间
收银台 URL,用于前端跳转，引导客户完成支付

3. 收款到账通知（异步）

平台按订单中的回调call_url推送结果。通知失败自动重试 3 次，间隔 10 秒。

  • 请求方式：POST
  • 数据类型：application/json
  • 回执要求：{"code":1,"msg":"操作成功"}
通知体示例
{
    "Id": "5678690426186186944",
    "OrderNo": "505910570990977408",
    "Asset": "Trx",
    "FromAddress": "TKUVtbiLuF52MackJiinWjpcXNeYxKe888",
    "ToAddress": "TKUVtbiLuF52MackJiinWjpcXNeYxFe888",
    "Money": 25.0,
    "Fee": 1.0,
    "IsClaim": false,
    "State": 2,
    "StateTime": "2025-08-01 14:13:56",
    "CreateTime": "2025-08-01 14:13:56"
}
我方平台订单号
商户订单号
币种
发送地址
接收地址
订单金额
手续费
是否手动认领
状态：1待存款；2已到账；4已超时；5无效订单
状态时间
订单建立时间

接收通知建议流程：验签 → 幂等校验(orderNo+Id) → 业务上分/入账 → 返回成功。

验签方式：Header 中取 token、sign、merchantId，然后计算sign：小写 md5(请求体 + token + 签名Key)，注意请求体为原始body

php中，请用$rawBody = $this->request->getInput();不能使用$this->request->param() 会把请求体body内容进行格式化。

回执示例
{"code":1,"msg":"操作成功"}

4. 收款作废

/api/Thrpay/inCancel

收款订单作废后，终止后续到账验证与通知。

请求参数

是，订单号
请求示例
{
  "orderNo": "122558566332"
}
响应示例
{
  "code": 1,
  "msg": "操作成功/失败时说明"
}

返回字段说明

状态码，1 表示成功，非 1 表示失败
返回消息，成功提示或失败原因说明

5. 收款认领

/api/Thrpay/incomplete

当客人付错金额时，可通过此接口手动认领。仅处理与订单地址匹配的链上交易。

请求参数

是，订单号
是，TRON链交易哈希
请求示例
{
  "orderNo": "122558566332",
  "tradeHash": "3c797c......01b2720"
}
响应示例
{
  "code": 1,
  "msg": "操作成功/失败时说明"
}

返回字段说明

状态码，1 表示成功，非 1 表示失败
返回消息，成功提示或失败原因说明

风控提示：TradeHash 与订单收款地址不匹配时平台不处理；恶意认领会触发封禁及处罚。

8. 创建付款订单

/api/Thrpay/outOrder

向指定地址付款，支持Trx|Usdt

请求参数

是，商户订单号
是，付款数量
是，Trx|Usdt
是，收款人地址
否，付款结果回调 URL
  • 付款前请先调用余额查询接口，余额不足会导致下单失败。
  • 订单号必须唯一，重复下单会失败。
  • 付款成功后平台会扣减商户余额并触发异步通知。
付款请求示例
{
  "orderNo": "122558566332",
  "money": "20.35",
  "asset": "Usdt",
  "toAddress": "TNhWGSkaQ......qSeFSCCCC",
  "call_url": "https://merchant.example.com/callback/out"
}
成功响应示例
{
    "code": 1,
    "msg": "操作成功",
    "data": "5678690426168186944"
}

返回字段说明

我方平台订单号

9. 付款结果通知（异步）

平台按订单中的回调call_url推送结果。通知失败自动重试 3 次，间隔 10 秒。

  • 请求方式：POST
  • 数据类型：application/json
  • 回执要求：{"code":1,"msg":"操作成功"}
通知体示例
{
    "Id": "5321960691641319346",
    "OrderNo": "505910570909077748",
    "Asset": "Trx",
    "ToAddress": "TPDoE6f----LLMrgSBB",
    "Money": 25.000,
    "TradeHash": "4769114----588515",
    "Fee": 1.00,
    "State": 5,
    "StateTime": "2025-08-01 16:29:48",
    "Remark": "",
    "CreateTime": "2025-08-01 16:29:48"
}
我方平台订单号
商户订单号
币种
接收地址
转账数量
交易哈希
手续费
状态：1待处理；2出款中；3出款故障；4出款失败；5出款完成；6订单撤销
状态时间
备注
建立时间

接收通知建议流程：验签 → 幂等校验(orderNo+Id) → 业务上分/入账 → 返回成功。

验签方式：Header 中取 token、sign、merchantId，然后计算sign：小写 md5(请求体 + token + 签名Key)，注意请求体为原始body

php中，请用$rawBody = $this->request->getInput();不能使用$this->request->param() 会把请求体body内容进行格式化。

回执示例
{"code":1,"msg":"操作成功"}

6. 收款订单详情

/api/Thrpay/findInOrder

返回收款订单详细信息

请求参数

是，订单号
收款详情请求示例
{
  "orderNo": "123443450098",
}
成功响应示例
{
    "code": 1,
    "msg": "操作成功",
    "data": {
        "Id": "5678690426168186944",
        "OrderNo": "505910570909977408",
        "MerchantId": "16501555404",
        "MerchantName": "测试商户",
        "Asset": "Trx",
        "FromAddress": "TKUVtbiluF52M……eYxMe66",
        "ToAddress": "TKUVtbiluF52M……eYxMe888",
        "Money": 25.0,
        "Fee": 1.0,
        "RealMoney": 0.0,
        "IsClaim": false,
        "State": 1,
        "StateTime": "2025-08-01 14:13:56",
        "CreateTime": "2025-08-01 14:13:56"
    }
}

返回字段说明

平台订单号
商户订单号
商户编号
商户名称
币种
付款地址
接收地址
订单金额
手续费
客户实际支付
是否手动认领
状态：1待存款；2已到账；4已超时；5无效订单
状态时间
订单建立时间

7. 收款订单列表

/api/Thrpay/findInOrders

返回收款订单列表信息

请求参数

否，集合值：1:待存款;2:已到帐;4:已超时;5:无效订单;
0正常、1认领
否，Trx|Usdt
否，开始时间，例：2025-07-20
否，结束时间，例：2025-08-30
否，页码，例：1
收款订单列表请求示例
{
  "orderNo": "123443450098",
}
成功响应示例
{
    "count": 2,
    "curPage": 1,
    "pageSize": 13,
    "code": 1,
    "msg": "操作成功",
    "data": [
        {
            "Id": "5678690426168186944",
            "OrderNo": "5059105709990777408",
            "MerchantId": "16501555404",
            "MerchantName": "测试商户",
            "Asset": "Trx",
            "UserId": "",
            "FromAddress": "TKUVtbiluF52M……eYxMe66",
            "ToAddress": "TKUVtbiluF52M……eYxMe888",
            "Money": 25.0,
            "Fee": 1.0,
            "RealMoney": 0.0,
            "IsClaim": false,
            "State": 1,
            "StateTime": "2025-08-01 14:13:56",
            "CreateTime": "2025-08-01 14:13:56"
        }
    ]
}

返回字段说明

总数量
当前页
每页数量
状态码
返回消息
平台订单号
商户订单号
商户编号
商户名称
币种
付款地址
接收地址
订单金额
手续费
客户实际支付
是否手动认领
状态：1待存款；2已到账；4已超时；5无效订单
状态时间
订单建立时间

10. 付款订单详情

/api/Thrpay/findOutOrder

返回付款订单详细信息。

请求参数

是，订单号
请求示例
{
  "orderNo": "50591057090977748"
}
响应示例
{
  "code": 1,
  "msg": "操作成功",
  "data": {
    "Id": "5321966916411319346",
    "OrderNo": "50591057090977748",
    "MerchantId": "165015550404",
    "MerchantName": "测试商户",
    "Asset": "Trx",
    "ToAddress": "TPDoE6f••••LLMrgSBB",
    "Money": 25.000,
    "TradeHash": "4769114••••588515",
    "Fee": 0.4769,
    "State": 1,
    "StateTime": "2025-08-01 16:29:48",
    "Remark": "",
    "TransId": "5552105108987146309",
    "CreateTime": "2025-08-01 16:29:48"
  }
}

返回字段说明

平台订单号
商户订单号
商户编号
商户名称
币种
接收地址
转账数量
交易哈希
手续费
状态：1待处理；2出款中；3出款故障；4出款失败；5出款完成；6订单撤销
状态时间
备注
执行流水ID
订单建立时间

11. 付款订单列表

/api/Thrpay/findOutOrders

返回付款订单列表信息。

请求参数

否，1待处理；2出款中；3出款故障；4出款失败；5出款完成；6订单撤销
否，Trx|Usdt
否，开始时间，例：2025-07-20
否，结束时间，例：2025-08-30
否，页码

限频：1 次 / 3 秒。

请求示例
{
  "state": "1",
  "asset": "Trx",
  "start": "2025-07-20",
  "end": "2025-08-30",
  "page": "1"
}
响应示例
{
  "count": 12,
  "curPage": 1,
  "pageSize": 13,
  "code": 1,
  "msg": "操作成功",
  "data": [
    {
      "Id": "5321966916411319346",
      "OrderNo": "505910570990977748",
      "MerchantId": "165015550547404",
      "MerchantName": "测试商户",
      "Asset": "Trx",
      "ToAddress": "TPDoE6f------LLMrgSBB",
      "Money": 25.000000,
      "TradeHash": "4769114------588515",
      "Fee": 3.00,
      "State": 1,
      "StateTime": "2025-08-01 16:29:48",
      "TimeConsuming": 0,
      "Remark": "",
      "TransId": "5552105108987146309",
      "CreateTime": "2025-08-01 16:29:48"
    }
  ]
}

返回字段说明

总数量
当前页
每页数量
状态码，1 表示成功
返回消息
我司订单号
商户订单号
商户编号
商户名称
币种
接收地址
转账数量
交易哈希
手续费
状态：1待处理；2出款中；3出款故障；4出款失败；5出款完成；6订单撤销
状态时间
耗时
备注
执行流水号
建立时间

12. 余额查询

余额查询

/api/Thrpay/findMerchant

返回实时可用余额

请求参数

是，固定值Balance
余额查询请求示例
{
  "type": "Balance",
}
成功响应示例
{
    "code": 1,
    "msg": "操作成功",
    "data": {
        "Trx": 1000.25,
        "Usdt": 89.56
    }
}

返回字段说明

TRX余额
USDT余额