An underpayment leaves a balance due; an overpayment creates an excess receipt to resolve. Neither should trigger an improvised refund or another full payment request. First verify what arrived, match it to the purchase, and decide separately whether to fulfill and how to settle the difference.
This playbook assumes the correct asset, network and destination. If those do not match, use the wrong-network incident playbook instead. Here, the problem is the amount, timing or allocation of an otherwise matching receipt.
The controls below are merchant operating and engineering recommendations, not a list of automatic Yolfi features. Examples are illustrative, not customer incidents.
Establish the amount before deciding the remedy
Preserve the original request: order reference, requested token amount, network, destination, quote basis and any expiry rule. Compare it with independently verified receipts that meet your confirmation policy, not a customer's wallet screenshot or balance estimate.
Keep three figures separate:
- Requested amount: what the payment instructions required.
- Verified receipts: matching transfers actually received and eligible for allocation.
- Unresolved balance: the shortfall or excess after previous allocations, credits and refunds.
Do not subtract your own later transfer costs from the customer's payment amount. Keep provider fees and accounting adjustments separate from evidence of what arrived.
An exchange withdrawal may deliver less than the customer intended if that service deducts a fee. Check the receipt rather than guessing. Conversely, a standard USDC or USDT transfer on Ethereum does not pay Ethereum gas by deducting USDC or USDT: Ethereum gas fees are paid in ETH. Do not advise customers to add a guessed stablecoin amount for gas.
For implementation, compare exact integer base units or exact decimal values using the asset's verified precision. Avoid binary floating-point comparisons and never round a shortfall away merely because the checkout displays fewer decimals.
An amount-exception decision table
Use this as an internal policy template. These are business classifications, not Yolfi API statuses.
| Verified situation | Fulfillment decision | Amount-resolution action | Control before closing |
|---|---|---|---|
| Full amount received within the applicable timing rule | Fulfill once after confirmation requirements are met | Allocate receipt to the order | Check prior allocations and fulfillment |
| Less than requested | Hold unless an authorized concession applies | Approve a tracked balance request, concession or refund | Record the remaining balance and owner |
| More than requested | Fulfill once only if payment acceptance rules are satisfied | Review excess for refund or agreed credit | Separate order allocation from excess |
| Several transfers reach the required total | Hold until aggregation is verified and allowed | Allocate each eligible transfer once | Do not assume the provider combines payments |
| Full amount arrives after expiry | Review timing, quote and order availability | Accept under policy or agree another resolution | Check linked replacement requests |
| Original and replacement requests both receive funds | Never fulfill twice | Reconcile both receipts and resolve the surplus | Lock the order against duplicate actions |
Give every exception a named owner and a next-update deadline. A receipt should not remain unallocated because support and finance each assume the other team is handling it.
Underpayments: request only an approved next step
Suppose a request requires 100 USDC, but the verified receipt is 98 USDC. The shortfall is 2 USDC. Preserve the original receipt; do not silently replace it with a new record showing 100.
Choose one documented outcome:
- Collect the balance. Verify that your integration can reconcile separate receipts. Issue a tracked request for the outstanding amount, linked to the same order, with current payment instructions.
- Accept a concession. An authorized person records the waived amount and accounting treatment. Do not claim that a merchant concession changes the provider's recognition rules.
- Return the partial receipt. Agree the refund terms and destination before executing the separate outbound payment.
Yolfi's partial-payment FAQ says incomplete payments are not confirmed and asks customers to contact the merchant. It makes same-address top-ups conditional on the merchant's system supporting them. Therefore, do not promise that sending the difference automatically completes the original Yolfi request.
If split-payment handling has not been verified, escalate before telling the customer to send more. Asking for another full payment while retaining the first partial receipt creates a predictable overpayment.
Set any small-shortfall policy before incidents occur. For example, define an approval limit, eligible purchases and an audit reason. There is no universal tolerance percentage: BTCPay Server documents its own configurable underpayment tolerance, but that is not evidence that Yolfi exposes the same setting.
Overpayments: separate the sale from the excess
A customer owes 100 USDT and sends 105 USDT. If the payment otherwise meets acceptance requirements, allocate 100 USDT to the purchase and track 5 USDT as an unresolved excess. Do not treat the difference as additional revenue or extra product entitlement by default.
Ask the customer to choose an available, policy-compliant resolution: a refund or an explicitly agreed credit. Explain any applicable fees before agreement, and check local consumer and accounting obligations. A small amount is not permission to retain funds silently.
Also distinguish an oversized transfer from a duplicate. Two transfers of 100 USDT against one 100 USDT purchase are two receipts, not one corrected receipt. Keep both transaction records, fulfill once and review the additional 100 USDT separately.
Late payments: expiry does not dispose of received funds
Record the payment-request deadline, transfer detection time and confirmation time separately. A payment observed before expiry but confirmed afterward is different from a transfer first received after the quote expired. Apply the documented rule; do not invent a universal grace period.
For late receipts, review:
- whether the original price remains valid;
- whether stock, capacity or access is still available;
- whether another request already paid the same order;
- whether a refund, credit or concession was already approved.
A token-denominated request for 100 USDC and a fiat-denominated request converted into crypto need not have identical late-payment policies. Preserve the original quotation and disclose any new quote rather than repricing history.
If a replacement request is necessary, link it to the original order in your records and warn the customer not to pay both. Continue monitoring the old attempt. Closing a support ticket does not stop a previously submitted transfer from later confirming.
Refund safely, without creating a second incident
A refund is a separate outbound payment, not an edit to the incoming transfer. Yolfi's non-custodial service explanation says payments go directly to the merchant's configured wallet. Do not assume Yolfi holds a refundable balance or automatically returns an excess.
Before authorizing a refund:
- Confirm the original receipt, customer claim and remaining refundable amount.
- Authenticate the requester through the established customer channel.
- Obtain and verify the intended refund asset, network and destination. Do not blindly return funds to the transaction sender; it may belong to an exchange or another intermediary.
- Agree the gross refund, fee treatment and expected net amount, subject to applicable obligations.
- Require approval under your wallet-security policy; record the reason and approver.
- Record the outbound transaction reference and verify its outcome before marking the refund complete.
Never request a seed phrase or private key. If a refund submission times out, investigate its transaction state before resending. An uncertain response is not proof that no payment was broadcast.
Make every resolution idempotent
Idempotency means retries cannot repeat a business action. Stripe's webhook guidance documents duplicate events and non-guaranteed ordering for Stripe; it is a useful engineering reference, not a statement of Yolfi's delivery contract.
For your own integration:
- Authenticate notifications using the provider's documented verification procedure.
- Persist incoming events durably and deduplicate with documented identifiers.
- Identify each receipt using its network and transaction reference, plus a transfer or event index where one transaction contains multiple relevant transfers.
- Enforce one allocation per receipt and one fulfillment per order with database constraints or equivalent transactional controls.
- Reserve an approved refund operation before dispatch, preventing concurrent workers from sending it twice.
A repeated webhook is not another payment. A second valid transfer is another receipt, but still not permission for a second shipment. Reconcile exceptions against both wallet evidence and business records before closure.
FAQ
Should we accept a tiny underpayment?
Only under an approved merchant policy. Record the concession separately and verify how the payment is recognized; do not assume an automatic tolerance exists.
Should an overpayment trigger an automatic refund?
Not without verified ownership, destination, amount and duplicate controls. Queue the excess for review unless a tested, authorized process safely handles it.
Can two partial transfers pay one order?
Your records can allocate multiple receipts if your policy allows it. Whether a payment provider recognizes them together must be verified separately.
Conclusion: close the balance, not just the ticket
Start with a clear Yolfi payment link, then keep the merchant's exception ledger alongside the payment record. Close a case only when the order allocation, fulfillment decision, remaining balance and any refund or credit agree. That prevents a small amount mismatch from becoming a second payment, a duplicate delivery or an unsafe refund.
