How to Create a USDT Payment Order
This guide walks through the complete flow for accepting a payment in USDT on the TRON network.
Unlike BRL and ARS payment orders, USDT payments are settled on-chain. After creating the order, your application must first detect the blockchain transaction and then wait until the payment has been fully processed and confirmed.
The flow consists of:
- Create the payment order.
- Wait for payment confirmation:
- Detect the blockchain transaction.
- Poll the payment order until it is completed.
Step 1 — Create Order
Request Examples
curl -X POST "/api/v1/payment/order" \
-H "Content-Type: application/json" \
-H "x-api-key: <your_api_key>" \
-H "Authorization: Bearer <your_access_token>" \
-d '{
"amount": "500.00",
"currency": "USDT"
}'
Response Behavior
A successful request returns 201 Created with the created payment order object.
The response include a qrData field containing QR code information.
Step 2 — Confirm Order
For USDT orders (settled on the Tron network), the confirmation flow is divided into two stages:
1. Webhook polling (payment detection)
First, you must poll the webhook endpoint every 15 seconds using the order's id until the payment metadata becomes available.
curl -X POST "/api/v1/payment/webhook/{orderId}/tron" \
-H "x-api-key: <your_api_key>" \
-H "Authorization: Bearer <your_access_token>"
- Continue polling until the response includes
providerMetadata. - At this stage:
- The payment status will still be
pending - But
providerMetadataindicates that the payment has been detected and is now being processed
- The payment status will still be
⚠️ Recommended polling interval: 15 seconds
Once providerMetadata is present, you can stop polling this endpoint.
2. Database polling (payment confirmation)
After the payment enters processing:
- Stop calling the webhook endpoint
- Start polling
/api/v1/payment/order/{orderId}for the payment status
At this stage, you should:
- Wait until the status changes from
pending→completed - No further webhook calls are required
Summary
- Confirm tron payment by order id → wait for
providerMetadata - Then poll payment order by id → wait for
completed
API References
Important Notes
- Payment orders initiate real financial operations. Ensure all fields are accurate before submitting.