Crypto payment underpayments, overpayments, late and duplicate transfers

Handle crypto payment underpayments, excess amounts, expired orders and duplicates with exact bookkeeping, per-deposit fees and verified Suawave callbacks.

Published , updated

Crypto payment underpayments and overpayments illustrated by bowls holding different quantities of blue and red glass spheres

Crypto payment underpayments need an amount policy before they need a support reply. Store the order total, selected ticker and deposit minimum. Count each eligible confirmed deposit once, using exact amounts. Treat an excess payment, an expired address and a repeated webhook as separate cases, because they require different decisions and don’t all produce a callback.

Suawave’s public address creation API doesn’t take your shop’s order total. It assigns a deposit address to a ticker and callback URL. Your shop decides whether the verified deposits pay for a 25 USDT purchase. The gateway decides whether each transfer is eligible for forwarding.

How should checkout handle crypto payment underpayments?

First distinguish an underpayment against the order total from a transfer below the gateway’s minimum. A 20 USDT deposit for a 25 USDT order can be eligible for forwarding while leaving the order unpaid. A transfer below the ticker minimum isn’t forwarded, produces no callback and doesn’t appear in public logs. These aren’t interchangeable waiting states.

Read minimum_transaction_coin from GET /{ticker}/info/ or the create response. Show it before the buyer sends, and check it again before suggesting a top-up. The minimum applied to a transfer is the value in force when it was first detected.

Checkout situation Gateway behavior Shop responsibility
Eligible deposit below order total Forwarded separately, with its own fees and confirmed callback Record it and keep the remainder unpaid
Deposit below ticker minimum No forwarding or public callback Explain the minimum and investigate through support
Eligible deposit above order total Full eligible deposit is forwarded after fees Record the excess and apply the shop’s policy
Same webhook delivered again Same event UUID Acknowledge without repeating its effects

The fees and minimums guide defines the gateway threshold. Your own acceptance threshold should be stored with the order so a later product price change doesn’t alter an existing checkout.

Can the customer send the missing amount later?

They can send another deposit while the order remains eligible, but every deposit must independently meet the ticker minimum. Suawave forwards each qualifying deposit separately. It doesn’t combine below-minimum fragments into one eligible transfer.

Consider a 25 USDT order where the buyer first sends 20 USDT. The missing 5 USDT is smaller than the shipped TRON USDT minimum of 10.00 USDT. Asking the buyer to “send the remaining 5” creates a second problem: that transfer is below the minimum. The shipped BEP20 USDT minimum is 1.00 USDT, but read the actual API value before giving instructions.

If the missing amount is below the live minimum, route the order to a person who can resolve the amount with the customer. Don’t automatically request a larger transfer that silently creates an overpayment. Checkout can prevent much of this by showing the exact amount and reminding the buyer to inspect any withdrawal deduction before confirming.

Should fees reduce the amount credited to the order?

Choose either gross receipt or net payout as the basis of your shop’s policy and name it explicitly. value_coin is the inbound deposit. value_forwarded_coin is what reached the payout address, after the total charge in fee_coin.

If a shop accepts gross payment, a qualifying 25 USDT deposit can satisfy a 25 USDT total even though the net payout is lower. If it requires a net amount, the same deposit may be insufficient. Don’t subtract fee_coin from value_forwarded_coin again; the latter already has the charge removed.

Keep amounts as decimal strings until converting them to integer units or an exact decimal type. TRON USDT has six decimal places in the registry; BSC USDT has eighteen. A generic assumption that every USDT ticker has six places breaks amount parsing across networks.

What happens when a customer overpays in crypto?

The public flow forwards the eligible deposit in full after its fees. It doesn’t cap the deposit at your shop’s expected total, and it doesn’t automatically refund the difference to the sender. A 30 USDT deposit for a 25 USDT order needs a shop decision about the extra 5 USDT.

Record the original deposit amount, the net payout and the excess according to your amount policy. Marking the order paid doesn’t erase the extra amount from your records. Keep a separate resolution state so support can see what remains to be handled.

Don’t treat txid_in as proof of a safe refund destination. The payer may have sent from an exchange or another service whose sending address isn’t their personal receiving address. Obtain and verify the intended destination through your own customer process before any separate repayment. Suawave’s public create API isn’t a refund API.

Two genuine deposits are also two payments, even if the customer says the second was accidental. Each can have its own confirmed callback and fees. A second payment after the order is paid should create an excess-payment record, not a second shipment.

Crypto payment underpayments accounting: 20 USDT received for a 25 USDT order leaves 5 unpaid, below the shipped TRC20 minimum

What happens to a crypto payment after order expiry?

Create returns expires_at, and repeating create for the same ticker and callback pair returns the original expiry. It doesn’t extend the window. After expiry, stop displaying the old deposit address and create a new order with a distinct callback URL if the buyer wants to try again.

The public API’s default expiry is 24 hours, but use the returned timestamp rather than assuming that default is deployed. The gateway also has a configured grace period, defaulting to two minutes. That grace is an allowance in eligibility checks, not an extra checkout window to advertise.

Suawave evaluates a transfer’s effective time using the earlier of observation time and block timestamp plus the configured clock-skew allowance. Finalizing after the deadline doesn’t by itself make a transfer late. The time of the transfer and the configured grace determine eligibility, rather than the time your shop eventually receives the callback.

A deposit whose effective time is at or after expiry plus grace is held for review. It isn’t credited or automatically forwarded, raises no public pending or confirmed callback, and doesn’t appear in public logs. The gateway doesn’t automatically refund it or complete the shop order. Support must investigate with the order details and transaction hash.

What if an operator later pays held funds to the merchant?

An operator’s manual sweep to the payout address sends no public callback. Your shop therefore needs manual reconciliation if support resolves a late-payment hold that way. Don’t build an automatic promise that every held payment eventually changes the checkout to paid.

Keep the old order and the replacement order distinct. Reusing an expired callback URL to get another address won’t work, because the ticker and callback pair is permanent. The address creation reference explains that identity rule.

How do you distinguish duplicate payments from duplicate webhooks?

A duplicate webhook is another delivery of an existing event. Retries preserve its uuid, so a durable uniqueness constraint can reject repeated processing. A duplicate payment is another actual transfer. It deserves a separate payment record even when its value matches the first transfer exactly.

Pending and confirmed callbacks have different UUIDs. Counting every new UUID as additional money would count one deposit twice. Only confirmed events should contribute to your accepted confirmed total, and your deposit record should retain the association between its pending and confirmed states.

Callback delivery can also be out of order. If confirmation has already been recorded, a late pending event mustn’t move the deposit back to waiting. Crypto payment finality explains why detection and confirmed forwarding are different events.

What should the database transaction contain?

For a verified confirmed callback, insert the event UUID, record the deposit and lock the relevant order while recalculating its accepted total. Store the resulting order transition in the same transaction. If the UUID already exists, return the normal acknowledgement without adding money or scheduling another shipment.

Use one durable fulfillment action per order, too. Two different genuine payments can arrive concurrently and both satisfy the amount threshold. Event deduplication alone doesn’t stop each request from trying to ship. An order lock and a unique fulfillment job prevent that race. These are integration design choices for your shop, not extra parameters on Suawave’s create endpoint.

Crypto payment underpayments decision flow for duplicate events, below-minimum deposits, late transfers, unpaid balances and excess

What should support check when the totals don’t match?

Retrieve the original order’s logs using its stored callback URL, and keep that full URL private. It acts as the capability for retrieving logs. Compare eligible entries with the confirmed events you recorded. sent means forwarding confirmed without an acknowledged confirmed callback; done means that callback was acknowledged.

Empty logs don’t prove no money was sent. Below-minimum, unsupported and late transfers can be absent. Ask for the transaction hash and selected network, then check the destination and timing. Don’t tell the customer to pay again solely because your callback handler has no event.

Before releasing a checkout change, exercise the amount policy with a partial payment, an excess payment, a second genuine deposit and a repeated delivery of the same event. Use the webhook handling guide for the signature and acknowledgement path. If network minimums force too many small orders into support, revisit the route offered first using USDT TRC20 vs BEP20.