Payment API Docs (TRON TRX/USDT) · Ver 1.86

Developer documentation for authentication, collection orders, payout orders, asynchronous callbacks and balance queries.

API host: https://api.tronspay.com Format: POST + application/json

1. Authentication Notes

Before integration, contact the business team to open a merchant account and obtain merchantId and the signing Key.

Each request must include token, sign and merchantId in the header.

  • token: request timestamp
  • merchantId: merchant identifier
  • sign: lowercase md5(requestBody + token + signKey)
https://api.tronspay.com
POST
application/json
UTF-8

In production, validate token freshness, record signature logs and reject replay requests.

Signing example
requestBody = "{\"orderNo\":\"122558566332\",\"asset\":\"Usdt\"}"

token = "1734029562000"
key = "merchant-sign-key"
sign = md5(requestBody + token + key).toLowerCase()
Success response
{
  "code": 1,
  "msg": "Success",
  "data": {}
}

Response fields

Status code: 0 failed, 1 success, 1001 sign error
Response message

2. Create Collection Order

/api/Thrpay/inOrder

Create a collection order and return the cashier URL and receiving address for the user to complete payment.

Request fields

Required, unique merchant order number
Required, Trx or Usdt
Required, supports up to 3 decimals
Optional callback URL after funds arrive
  • Duplicate order numbers return a failure response.
  • After success, redirect the frontend to the cashier URL.
Request example
{
  "orderNo": "122558566332",
  "asset": "Usdt",
  "money": "20.53",
  "call_url": "https://merchant.example.com/callback/in"
}
Success response
{
  "code": 1,
  "msg": "Success",
  "data": {
    "Id": "5678690426168186944",
    "OrderNo": "505910570909777408",
    "MerchantId": "1650155505404",
    "MerchantName": "Demo Merchant",
    "Asset": "Usdt",
    "ToAddress": "TKUVtbilLu2Ma...XN2Ke888",
    "Money": 25.0,
    "Fee": 1.0,
    "State": 1,
    "CreateTime": "2025-08-01 14:13:56",
    "Cashier": "https://x.x.com/x.html?id=2"
  }
}

Response fields

Platform order number
Merchant order number
Merchant ID
Merchant name
Asset type
Receiving address
Order amount
Fee
Whether manual claim is used
State: 1 pending, 2 credited, 4 expired, 5 invalid
Creation time
Cashier URL for frontend redirect

3. Collection Callback

The platform pushes callbacks to the order call_url. Failed notifications are retried automatically.

  • Method: POST
  • Content type: application/json
  • Ack body: {"code":1,"msg":"Success"}
Notification body
{
  "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"
}
Platform order number
Merchant order number
Asset type
Sender address
Receiving address
Order amount
Fee
Whether manual claim is used
State: 1 pending, 2 credited, 4 expired, 5 invalid
State time
Creation time

Recommended flow: verify sign → verify idempotency (orderNo + Id) → credit merchant balance → return success.

Use the raw request body when recalculating the sign.

Ack example
{"code":1,"msg":"Success"}

4. Cancel Collection Order

/api/Thrpay/inCancel

Cancel a pending collection order and stop later arrival checks and callbacks.

Request fields

Required, merchant order number
Request example
{
  "orderNo": "122558566332"
}
Response example
{
  "code": 1,
  "msg": "Success"
}

Response fields

1 means success, any other value means failure
Response message

5. Manual Claim

/api/Thrpay/incomplete

Manually claim a transfer when the payer sends an unexpected amount but the on-chain transfer still matches the order address.

Request fields

Required, merchant order number
Required, TRON transaction hash
Request example
{
  "orderNo": "122558566332",
  "tradeHash": "3c797c......01b2720"
}
Response example
{
  "code": 1,
  "msg": "Success"
}

Response fields

1 means success, any other value means failure
Response message

If tradeHash does not match the order address, the platform will reject the claim.

6. Collection Order Detail

/api/Thrpay/findInOrder

Return the detail of one collection order.

Request fields

Required, merchant order number
Request example
{
  "orderNo": "123443450098"
}
Success response
{
  "code": 1,
  "msg": "Success",
  "data": {
    "Id": "5678690426168186944",
    "OrderNo": "505910570909977408",
    "MerchantId": "16501555404",
    "MerchantName": "Demo Merchant",
    "Asset": "Trx",
    "FromAddress": "TKUVtbiluF52M...YxMe66",
    "ToAddress": "TKUVtbiluF52M...YxMe888",
    "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"
  }
}

Response fields

Platform order number
Merchant order number
Merchant ID
Merchant name
Asset type
Sender address
Receiving address
Order amount
Fee
Actual paid amount
Whether manual claim is used
State: 1 pending, 2 credited, 4 expired, 5 invalid
State time
Creation time

7. Collection Order List

/api/Thrpay/findInOrders

Return a paged list of collection orders.

Request fields

Optional: 1 pending, 2 credited, 4 expired, 5 invalid
Optional: 0 normal, 1 manually claimed
Optional, Trx or Usdt
Optional, start date such as 2025-07-20
Optional, end date such as 2025-08-30
Optional page number
Request example
{
  "orderNo": "123443450098"
}
Success response
{
  "count": 2,
  "curPage": 1,
  "pageSize": 13,
  "code": 1,
  "msg": "Success",
  "data": [
    {
      "Id": "5678690426168186944",
      "OrderNo": "5059105709990777408",
      "MerchantId": "16501555404",
      "MerchantName": "Demo Merchant",
      "Asset": "Trx",
      "UserId": "",
      "FromAddress": "TKUVtbiluF52M...YxMe66",
      "ToAddress": "TKUVtbiluF52M...YxMe888",
      "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"
    }
  ]
}

Response fields

Total count
Current page
Page size
Status code
Response message
Platform order number
Merchant order number
Merchant ID
Merchant name
Asset type
Sender address
Receiving address
Order amount
Fee
Actual paid amount
Whether manual claim is used
State: 1 pending, 2 credited, 4 expired, 5 invalid
State time
Creation time

8. Create Payout Order

/api/Thrpay/outOrder

Send funds to a target address, supporting Trx and Usdt.

Request fields

Required, merchant order number
Required, payout amount
Required, Trx or Usdt
Required, receiving address
Optional payout callback URL
  • Query merchant balance before payout to avoid insufficient-balance errors.
  • Merchant order numbers must be unique.
  • After success, merchant balance is deducted and an asynchronous callback is sent.
Request example
{
  "orderNo": "122558566332",
  "money": "20.35",
  "asset": "Usdt",
  "toAddress": "TNhWGSkaQ......qSeFSCCCC",
  "call_url": "https://merchant.example.com/callback/out"
}
Success response
{
  "code": 1,
  "msg": "Success",
  "data": "5678690426168186944"
}

Response fields

Platform payout order number

9. Payout Callback

The platform pushes payout results to the configured call_url. Failed callbacks are retried automatically.

  • Method: POST
  • Content type: application/json
  • Ack body: {"code":1,"msg":"Success"}
Notification body
{
  "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"
}
Platform order number
Merchant order number
Asset type
Receiving address
Transfer amount
Transaction hash
Fee
State: 1 pending, 2 processing, 3 gateway issue, 4 failed, 5 completed, 6 canceled
State time
Remark
Creation time

Recommended flow: verify sign → verify idempotency → update payout status → return success.

Ack example
{"code":1,"msg":"Success"}

10. Payout Order Detail

/api/Thrpay/findOutOrder

Return the detail of one payout order.

Request fields

Required, merchant order number
Request example
{
  "orderNo": "50591057090977748"
}
Response example
{
  "code": 1,
  "msg": "Success",
  "data": {
    "Id": "5321966916411319346",
    "OrderNo": "50591057090977748",
    "MerchantId": "165015550404",
    "MerchantName": "Demo Merchant",
    "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"
  }
}

Response fields

Platform order number
Merchant order number
Merchant ID
Merchant name
Asset type
Receiving address
Transfer amount
Transaction hash
Fee
State: 1 pending, 2 processing, 3 gateway issue, 4 failed, 5 completed, 6 canceled
State time
Remark
Execution transaction ID
Creation time

11. Payout Order List

/api/Thrpay/findOutOrders

Return a paged list of payout orders.

Request fields

Optional: 1 pending, 2 processing, 3 gateway issue, 4 failed, 5 completed, 6 canceled
Optional, Trx or Usdt
Optional start date, e.g. 2025-07-20
Optional end date, e.g. 2025-08-30
Optional page number

Rate limit: 5 requests per 3 seconds.

Request example
{
  "state": "1",
  "asset": "Trx",
  "start": "2025-07-20",
  "end": "2025-08-30",
  "page": "1"
}
Response example
{
  "count": 12,
  "curPage": 1,
  "pageSize": 13,
  "code": 1,
  "msg": "Success",
  "data": [
    {
      "Id": "5321966916411319346",
      "OrderNo": "505910570990977748",
      "MerchantId": "165015550547404",
      "MerchantName": "Demo Merchant",
      "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"
    }
  ]
}

Response fields

Total count
Current page
Page size
Status code
Response message
Platform order number
Merchant order number
Merchant ID
Merchant name
Asset type
Receiving address
Transfer amount
Transaction hash
Fee
State: 1 pending, 2 processing, 3 gateway issue, 4 failed, 5 completed, 6 canceled
State time
Time consuming
Remark
Execution transaction ID
Creation time

12. Balance Query

/api/Thrpay/findMerchant

Return the merchant's real-time available balance.

Request fields

Required, fixed value Balance
Request example
{
  "type": "Balance"
}
Success response
{
  "code": 1,
  "msg": "Success",
  "data": {
    "Trx": 1000.25,
    "Usdt": 89.56
  }
}

Response fields

TRX balance
USDT balance