Skip to main content

Handle Underpaid Orders

Overview​

An order becomes underpaid when a payer sends less than the required amount. This only applies to USDT orders, since the payer manually enters the transfer amount on the Tron network.

During the USDT confirmation flow, the webhook polling endpoint will detect the partial payment and return the order with status underpaid, alongside totalAmount and pendingAmount fields. The totalAmount represents the total amount paid, and pendingAmount the remaining amount still owed to complete the transaction.

This cycle can repeat multiple times — each partial payment reduces the remaining balance until the full amount is covered and the order reaches completed.

When It Happens​

While polling the webhook endpoint:

curl -X POST "/api/v1/payment/webhook/{orderId}/tron" \
  -H "Authorization: Bearer <your_access_token>"

If the payer sent an incomplete payment, the response will include:

  • status: "underpaid"
  • totalAmount: the total amount paid so far
  • pendingAmount: the remaining amount needed to fulfill the original order

Resolution Flow​

To resolve an underpaid order, create a new payment order using pendingAmount as the amount and restart the full confirmation flow. Repeat this process for each partial payment until the full amount has been received.

Step 1 — Create a new order for the remaining amount​

curl -X POST "/api/v1/payment/order" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
    "amount": "<pendingAmount>",
    "currency": "USDT"
  }'

Replace <pendingAmount> with the value returned in the underpaid order response.

Step 2 — Restart the USDT confirmation flow​

Once the new order is created, follow the standard two-stage USDT confirmation flow:

  1. Poll POST /api/v1/payment/webhook/{orderId}/tron every 15 seconds until providerMetadata appears.
  2. Then poll GET /api/v1/payment/order/{orderId} until the status reaches completed.

If the payer sends another partial payment, the webhook endpoint will return underpaid again with an updated totalAmount and pendingAmount. Create another new order for the pendingAmount and repeat from Step 1 until the status is completed.

API References