Skip to main content

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:

  1. Create the payment order.
  2. 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 providerMetadata indicates that the payment has been detected and is now being processed

⚠️ 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​

  1. Confirm tron payment by order id → wait for providerMetadata
  2. 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.