Tron Payment Gateway API

The Tron Payment Gateway API allows you to accept cryptocurrency payments (TRX and USDT TRC-20) through a simple RESTful interface. This documentation covers all available endpoints, authentication, request/response formats, and error handling.

API Tester

TRON address (34 characters, starts with T)
Response

Authentication

All API requests must include your API key for authentication. You can provide it in two ways:


Header Authentication (Recommended)

X-API-Key: pk_your_api_key_here

Query Parameter

GET /payment/status/12345?api_key=pk_your_api_key_here
Rate Limiting: 1000 requests per minute per API key

Response Format

All API responses follow a consistent JSON format:

{ "success": true, "data": { // Response data } }

Error Response

{ "error": "ERROR_CODE", "message": "Human readable error message", "details": { // Additional error details (optional) } }

Common Error Codes

Code HTTP Status Description
VALIDATION_ERROR 422 Invalid input data
PAYMENT_NOT_FOUND 404 Payment not found
PARTNER_ERROR 400 Partner-related error
WALLET_ERROR 400 Wallet-related error
API_LIMIT_EXCEEDED 503 API rate limit exceeded
INSUFFICIENT_WALLETS 400 No available wallets
PAYMENT_NOT_COMPLETED 400 Payment not in completed status

Example Request

{ "transaction_id": "order_12345", "asset": "USDT", "amount_usd": "100.50", "postback_url": "https://yoursite.com/callback" }

Example Response

{ "success": true, "data": { "transaction_id": "order_12345", "wallet_address": "TXnNyJhWrbVCty8tFqArwZZaZkPzAkjhom", "asset": "USDT", "amount_usd": "100.50", "amount_crypto": "100.50000012", "expires_at": "2024-01-15T10:25:00.000000Z", "status": "pending" } }

API Endpoints

POST /api/payment/create
Creates a new payment request

Parameters

Parameter Type Required Description
transaction_id string Yes Unique identifier for this payment (max 255 chars)
asset string Yes Cryptocurrency type: TRX or USDT
amount_usd decimal Yes Amount in USD (0.01 - 999999.99)
postback_url string No URL for payment notifications (max 500 chars)

Example Request

{ "transaction_id": "order_12345", "asset": "USDT", "amount_usd": "100.50", "postback_url": "https://yoursite.com/callback" }

Example Response

{ "success": true, "data": { "transaction_id": "order_12345", "wallet_address": "TXnNyJhWrbVCty8tFqArwZZaZkPzAkjhom", "asset": "USDT", "amount_usd": "100.50", "amount_crypto": "100.50000012", "expires_at": "2024-01-15T10:25:00.000000Z", "status": "pending" } }
GET /api/payment/{transactionId}/status
Retrieves payment status

Example Response

{ "success": true, "data": { "transaction_id": "order_12345", "status": "completed", "asset": "USDT", "amount_usd": "100.50", "amount_crypto": "100.50000012", "amount_received": "100.50000012", "wallet_address": "TXnNyJhWrbVCty8tFqArwZZaZkPzAkjhom", "created_at": "2024-01-15T10:15:00.000000Z", "expires_at": "2024-01-15T10:25:00.000000Z", "blockchain": { "txid": "a1b2c3d4e5f6789...", "from_address": "TSender123...", "block_timestamp": 1642248900000, "block_number": 45678901 } } }
GET /api/payments
Retrieves payment history with pagination

Query Parameters

Parameter Type Description
page integer Page number (default: 1)
limit integer Items per page (1-100, default: 50)
status string pending, completed, expired, failed
asset string TRX or USDT
GET /api/payments/unprocessed
Retrieves payments that couldn't be automatically processed

Example Response

{ "success": true, "data": [ { "transaction_id": "order_12346", "status": "expired", "asset": "TRX", "amount_usd": "50.00", "amount_crypto": "1000.00000034", "wallet_address": "TXnNyJhWrbVCty8tFqArwZZaZkPzAkjhom", "created_at": "2024-01-15T09:00:00.000000Z", "expires_at": "2024-01-15T09:10:00.000000Z" } ] }
POST /api/payment/{transactionId}/resend-postback
Manually resends a postback notification for a completed payment

Example Response

{ "success": true, "data": { "postback_sent": true, "message": "Postback sent successfully" } }
GET /api/partner/wallets
Retrieves all wallets associated with your account

Example Response

{ "success": true, "data": [ { "id": 1, "address": "TXnNyJhWrbVCty8tFqArwZZaZkPzAkjhom", "is_active": true, "usage_count": 25, "last_used_at": "2024-01-15T10:15:00.000000Z", "created_at": "2024-01-10T08:00:00.000000Z" } ] }
GET /api/partner/wallets/add

POST /api/partner/wallets
Adds a new wallet to your account

Parameters

Parameter Type Required Description
address string Yes TRON wallet address (34 characters, starts with T)

Example Request

{ "address": "TXnNyJhWrbVCty8tFqArwZZaZkPzAkjhom" }

Example Response

{ "success": true, "data": { "id": 6, "address": "TXnNyJhWrbVCty8tFqArwZZaZkPzAkjhom", "is_active": true, "created_at": "2024-01-15T11:00:00.000000Z" } }

Error Responses

// Wallet Limit Exceeded { "error": "WALLET_LIMIT_EXCEEDED", "message": "Maximum 15 wallets allowed" } // Wallet Already Exists { "error": "WALLET_EXISTS", "message": "Wallet address already exists" }
PUT /api/partner/wallets/{walletId}
Updates wallet settings (activate/deactivate)

Parameters

Parameter Type Required Description
is_active boolean Yes Wallet active status

Example Request

{ "is_active": false }

Example Response

{ "success": true, "data": { "id": 1, "address": "TXnNyJhWrbVCty8tFqArwZZaZkPzAkjhom", "is_active": false } }
GET /api/partner/info
Retrieves partner account information

Example Response

{ "success": true, "data": { "id": 123, "name": "Your Company Name", "email": "[email protected]", "balance": "1000.00000000", "max_wallets": 15, "status": "active", "default_postback_url": "https://yoursite.com/callback", "wallets_count": 5, "active_wallets_count": 5 } }

Payment Statuses

Status Description
pending Waiting for payment
completed Payment received and confirmed
expired Payment expired (30 minutes timeout)
failed Payment failed

Postback Notifications

When a payment is completed, the system will send a POST request to your postback URL:

{ "transaction_id": "order_12345", "status": "completed", "asset": "USDT", "amount_usd": "100.50", "amount_crypto": "100.50000012", "amount_received": "100.50000012", "wallet_address": "TXnNyJhWrbVCty8tFqArwZZaZkPzAkjhom", "created_at": "2024-01-15T10:15:00.000000Z", "expires_at": "2024-01-15T10:25:00.000000Z", "blockchain": { "txid": "a1b2c3d4e5f6789...", "from_address": "TSender123...", "block_timestamp": 1642248900000, "block_number": 45678901 } }
Retry Logic: Up to 3 attempts with intervals of 1, 5, and 15 minutes. Your endpoint should respond with HTTP 200 status.