A customer underpaid, overpaid, or sent on the wrong chain
What happens when a transfer doesn't match the order amount, asset, or chain — and how to recover the funds.
StableOps promotes an order to detected only when a transfer matches the order
exactly on every key:
- the receiving address (scoped to your organization and environment),
- the chain and asset, and
- the amount (compared in smallest units after applying token decimals).
The order must still be in created for the match to apply. If any one of these
differs, the transfer is recorded but the order does not advance. No
payment.detected is sent, and the order keeps waiting until it
expires.
Underpayment or overpayment
A transfer for any amount other than the exact amount you requested will not
match the order. StableOps does not partially fulfill an order or accept a
"close enough" amount. 9.99 and 10.01 are both misses for a 10.00 order.
What to do:
- Always show the customer the exact amount from
paymentInstructionsand don't let them edit it. Many wallets let users type their own amount. That is the most common cause of a stuck order. - If a customer underpays or overpays anyway, the order will expire on schedule. Resolve the difference (refund, top-up request, or manual credit) out of band against the address the funds actually landed on.
Wrong chain or wrong asset
An order only listens on the (chain, asset) pairs you passed in
acceptedAssets. A transfer on a chain or asset you didn't accept (or USDT
sent to an order that only accepts USDC) has no allocated address to match
against, so it never promotes the order.
Only the (chain, asset) combinations on the
supported assets tables can be accepted at all; anything outside them
is rejected at create time.
Recovering misdirected funds
You recover funds yourself. StableOps only tracks and reconciles payments but never holds your keys or moves funds for you.
- With BYO addresses, the funds arrived at an address you control, so you can reconcile or refund them directly from your own treasury tooling.
- The transfer is still visible in your chain history and (if it hit a scanned address) in StableOps as an event that didn't match any open order.
Avoiding stuck orders
- Render the amount and chain from
paymentInstructionsverbatim; never let the customer change them. - Give the order a realistic expiration window so a mistyped payment doesn't leave the order open indefinitely.
- Fulfill on
payment.finalized, never on a manual "I sent it" claim.
Related
How is this guide?
Last updated
Testnet USDC / USDT faucets
Faucet links for testnet USDC / USDT on every chain StableOps supports — use these when working in the playground or sandbox.
When orders expire and what happens if a payment never arrives
How order expiration works, when payment.expired fires, and what happens to a transfer that arrives too late.