Handle Overpaid Orders
Overview
An order is overpaid when a payer sends more than the required amount. This only applies to USDT orders, since the payer manually enters the transfer amount on the Tron network.
There is no overpaid status. An overpaid order follows the normal flow and ends with status completed, but the excess is reported in pendingAmount. A completed order with a pendingAmount greater than 0 is an overpaid order.
How to Detect It
Follow the standard USDT confirmation flow and, once the order reaches completed, read the order:
curl -X GET "/api/v1/payment/order/{orderId}" \
-H "x-api-key: <your_api_key>" \
-H "Authorization: Bearer <your_access_token>"
Then check for an excess:
const isOverpaid =
order.status === "completed" && Number(order.pendingAmount) > 0;
Example response (relevant fields only):
{
"totalAmount": "4.00",
"amount": "2.00",
"pendingAmount": "2.00",
"status": "completed"
}
| Field | Meaning in an overpaid order |
|---|---|
amount | The amount originally requested for the order |
totalAmount | The total amount actually received from the payer |
pendingAmount | The excess received above the requested amount |
status | completed — the order is fulfilled, there is no new status |
In the example above, the order was created for 2.00 USDT but the payer sent 4.00, so the excess is 2.00.
Underpaid vs. Overpaid
| Case | Payer sends | Order status | pendingAmount means | Action required |
|---|---|---|---|---|
| Underpaid | Less than requested | underpaid | Amount still owed | Create a new order for pendingAmount — see Handle Underpaid Orders |
| Overpaid | More than requested | completed | Amount received in excess | None to complete the order; detect it with status === "completed" && Number(pendingAmount) > 0 |
Note
Because overpaid orders are not flagged by a dedicated status, integrations that only check
status === "completed"will not notice the excess. Always checkpendingAmountas well when handling USDT orders.
API References