Skip to main content

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"
}
FieldMeaning in an overpaid order
amountThe amount originally requested for the order
totalAmountThe total amount actually received from the payer
pendingAmountThe excess received above the requested amount
statuscompleted — 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​

CasePayer sendsOrder statuspendingAmount meansAction required
UnderpaidLess than requestedunderpaidAmount still owedCreate a new order for pendingAmount — see Handle Underpaid Orders
OverpaidMore than requestedcompletedAmount received in excessNone 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 check pendingAmount as well when handling USDT orders.

API References