A customer underpaid, overpaid, or sent on the wrong chain

Learn how StableOps records underpayments, overpayments, wrong-chain transfers, and late payments, plus when to use its refund API or recover funds manually.

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
the amount, compared in smallest units after applying token decimals

The order must also be in created. If any key differs, the order does not advance, no payment.detected event is sent, and the order keeps waiting until it expires.

If StableOps supports and is scanning the chain, asset, and address where the transfer occurred, it still saves the on-chain event and records an exceptional payment attempt. For example, an incorrect amount is classified as amount_mismatch, while a transfer received after expiration is classified as late_payment. A transfer on an unsupported or unmonitored network might not appear in StableOps, so investigate it through the relevant block explorer or merchant wallet.

Underpayment or overpayment

A transfer for any amount other than the exact amount you requested will not match the order. StableOps does not combine transfers, 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 paymentInstructions and do not let them edit it. Wallets that let users enter their own amount are a common cause of stuck orders.
If the customer underpays or overpays anyway, let the original order expire and then follow your policy for a refund, top-up request, or manual credit.
If you request a top-up, do not expect two transfers with different amounts to combine and complete the original order automatically. Create a new payment request or combine the outcome manually in your approved merchant ledger flow.

Wrong chain or wrong asset

An order listens only on the (chain, asset) pairs passed in acceptedAssets. A transfer on a chain or asset the order did not accept, or USDT sent to an order that only accepts USDC, cannot match the original order.

On EVM networks, the same textual 0x… address can exist on multiple chains. Even if funds arrive at an address with the same text, a transfer on a network different from the payment instruction is still a wrong-chain payment and does not complete the order.

Only the (chain, asset) combinations in the supported assets tables can be accepted. Unsupported combinations are rejected when an order is created, and StableOps does not guarantee discovery of transfers on unsupported networks or assets.

When the refund API applies

The StableOps refund API applies only to a finalized payment. Such an order has an exactly matched source payment event, so you can create a separate non-custodial refund request and then sign and broadcast the refund transaction with your merchant wallet.

Underpayments, overpayments, wrong-chain transfers, wrong-asset transfers, and late payments did not move the original order to finalized, so you cannot call the refund API against that order. Preserve the original order and exceptional payment record, handle the funds with your own treasury tooling, and record the refund, top-up, or manual credit as a separately approved exception. See how to handle underpayments, overpayments, and wrong-network transfers for the complete workflow.

Recovering misdirected funds

You recover the funds yourself. StableOps does not hold your private keys or sign and broadcast fund transfers for you.

With BYO addresses, funds usually arrive at an address you control. Confirm that your merchant wallet supports the actual chain and asset before deciding whether to refund or credit the payment.
Do not automatically refund to the source address. The payment might have come from an exchange, custodial wallet, or smart contract. Ask the customer to confirm the refund chain, asset, and destination address.
Preserve the original order, transaction hash, actual chain, asset, amount, decision, approver, and final refund transaction hash. Do not rewrite the original order state to make an exceptional payment appear matched.

Avoiding stuck orders

Render the amount, chain, asset, and address from paymentInstructions verbatim, and do not let the customer change them.
Give the order a realistic expiration window so a mistyped payment does not leave it open indefinitely.
Fulfill on payment.finalized, never on a manual "I sent it" claim.
Before launch, test an underpayment, overpayment, wrong-chain transfer, and late payment, and assign support, finance, and treasury owners to each exception.