Stablecoin On/Off-Ramp Failure Runbook for Operators

A stablecoin on-ramp or off-ramp does not fail in one place. It fails on a specific leg, and the entire diagnostic skill is localizing the failure to that leg before you touch anything. A deposit that has not arrived is a different problem depending on whether the fiat bank has not credited the provider, the provider is holding the session for screening, or the on-chain mint is still waiting for confirmations — and acting on the wrong assumption is how operators turn a delay into a duplicate send.

This runbook owns failure handling. It does not restate the on/off-ramp cost economics, the settlement-loop anatomy, or the compliance-stack deep dive — those are linked where relevant. Read this when something is stuck, wrong, or screened, and you need to know which leg failed and what you can and cannot promise about recovering it.

Direct answer

On/off-ramp failures cluster into layers, and the move is to localize the failure to a single leg before acting: the fiat bank leg, the ramp-provider leg, the blockchain transaction leg, the wallet/compliance screening leg, and the treasury/liquidity leg. Each leg has a distinct failure signature and a distinct escalation owner.

The constraint that shapes everything: on-chain transfers are irreversible once confirmed. A wrong-address or wrong-chain send is generally unrecoverable — there is no chargeback and no general clawback. Recovery, where it exists at all, depends on counterparty goodwill (a custodial exchange that controls the destination address) or a specific documented refund mechanism on the rail you used. A “refund” is a new transfer in the opposite direction, not a reversal of the original. Stablecoin transfers are not chargeback-style payments — say that plainly to customers.

Depeg and conversion exposure is an operational timing and liquidity risk on the ramp legs — a mark-to-market on the conversion leg and a gap between quote and settlement — not a market prediction. Before escalating anything, capture the chain, transaction hash, source and destination address, network, amount and token, the reference or memo, and the provider session or reference ID. See stablecoin for the base term.

Stablecoin on/off-ramp flow map

A stablecoin payment is a relay across legs, each owned by a different party. The settlement-loop anatomy covers the full flow; the abridged map a failure investigation needs:

On-ramp (fiat in → stablecoin out):

1. Fiat bank leg — the payer funds the ramp provider via ACH, wire, or a local rail. Money leaves a bank and must arrive at the provider’s account with the right reference.
2. Ramp-provider leg — the provider runs KYC/identity, sanctions screening, and fraud checks, then accepts the funding. Stripe’s onramp, as one public example, exposes this as session states moving from initialized to requires_payment to fulfillment_processing.
3. Blockchain transaction leg — the provider issues (mints or transfers) the stablecoin to the destination address on a specific chain. The transaction is broadcast, then confirmed. Stripe populates the on-chain transaction hash only at fulfillment_complete.

Off-ramp (stablecoin in → fiat out) runs the relay in reverse: an on-chain transfer in to the provider, provider screening and conversion, then a fiat payout to a destination bank account.

Cutting across all of it is the wallet/compliance screening leg (which can hold either direction) and the treasury/liquidity leg (the conversion rate, available liquidity, and limits). A deposit or withdrawal is “stuck” on exactly one of these — your job is to find which.

Failure layer model: fiat, ramp, blockchain, compliance, treasury

This six-leg model frames the whole runbook. Five legs are external systems that can fail; the sixth is PaymentBrief operator guidance — the checklists below are operator guidance, not vendor behavior.

The discipline: name the leg first. Every section below maps a real failure to one of these rows.

On-ramp failure scenarios

Fiat deposit not credited (fiat bank leg). The payer’s bank shows the money sent, but the provider has not accepted funding. Causes: ACH/wire still in transit, a missing or wrong payment reference so the provider cannot match the deposit, or a sender-name mismatch that fails the provider’s matching rule. Resolution: pull the bank transfer reference and value date, confirm the reference matches what the provider expects, and check the provider has not bounced the funds. This is a bank-leg and reference problem, not a chain problem — there is no tx hash yet.

KYC / screening hold (ramp-provider leg). The funding arrived but the session will not progress because the provider is running identity or sanctions checks. In Stripe’s public onramp taxonomy, a hard stop here surfaces as the session status = rejected, which Stripe documents as the provider rejecting the customer (KYC, sanctions, or fraud). Other providers expose their own status vocabularies — confirm the exact values against your provider. Resolution lives with the provider, not the bank or the chain; see the compliance section for the screening leg specifically.

Pending chain confirmation (blockchain transaction leg). The provider accepted payment and broadcast the on-chain transfer, but the stablecoin has not “arrived” because the destination chain is still confirming. Stripe, for example, only populates the on-chain transaction hash at fulfillment_complete. Resolution: get the tx hash, look it up on a block explorer for that chain, and read the confirmation count. A transfer that is broadcast but unconfirmed is normal in-flight state, not a failure — do not retry it.

Unsupported funding method (ramp-provider leg). The payer tried a funding rail or instrument the provider does not support for that corridor or account tier. This fails fast at the provider and never reaches the chain. Resolution: confirm the provider’s supported funding methods for the corridor and route the payer to a supported one.

Off-ramp failure scenarios

The off-ramp inverts the on-ramp, and the failure modes invert with it.

Withdrawal stuck (blockchain or provider leg). The customer initiated an off-ramp but no fiat has landed. Localize: is the inbound on-chain transfer to the provider still confirming (read the tx hash), is the provider holding for screening, or has the provider converted but the fiat payout not yet left? Each is a different owner.

Bank-transfer mismatch on the fiat-out leg (fiat bank leg). The provider says it paid out, but the beneficiary bank has not credited the customer. The usual culprits mirror the on-ramp: a missing reference or memo, or a sender-name / beneficiary-name mismatch that triggers a bank-side hold or return. Resolution: obtain the payout’s bank reference from the provider and trace it on the beneficiary bank statement — the same third-leg bank match used in the PSP reconciliation runbook.

Screening hold on the fiat-out leg (compliance leg). The fiat payout can be held by the provider’s or the receiving bank’s screening even after the on-chain leg cleared. The funds are converted but the payout is paused pending review. Resolution sits with the provider’s compliance function.

Unsupported destination (provider leg). The customer requested a payout to a currency, country, or account type the provider does not serve. Fails at the provider before any conversion. Resolution: confirm supported off-ramp destinations and route accordingly.

Wrong-chain / wrong-address / unsupported-token handling

This is the section to internalize, because it is the one where the wrong reassurance does real damage.

On-chain transfers are irreversible once confirmed. Circle’s own terms state plainly that digital-asset transactions are final and irreversible and cannot be cancelled or reversed, and that an incorrect, incomplete, or incompatible recipient address — explicitly including an address on the wrong destination chain — results in permanent loss, with the issuer having no ability to reverse, cancel, or retrieve the assets. That is the public, durable position to anchor on.

The three failure shapes:

• Wrong chain. Sending a token to an address on a network where that token is not natively issued or bridged — for example, treating an address as if it lived on a chain the asset was never minted to. Cross-chain movement is a deliberate burn-and-mint operation (Circle’s CCTP burns USDC on the source chain and mints native USDC on the destination chain via an attestation); it is not something that happens automatically because two chains “look similar.” A raw send to the wrong chain is generally unrecoverable.
• Wrong address. A correctly-formatted address that is simply not the intended recipient. On a public chain there is no undo; the funds are now controlled by whoever holds that address’s keys.
• Unsupported token / network. Sending an asset the destination wallet, exchange, or chain does not recognize or credit.

Recovery is goodwill or custodial-only, and never promised. The only realistic paths are: a custodial counterparty (an exchange or known entity that controls the destination address) choosing to cooperate, or a specific documented refund mechanism if the particular rail provides one. Neither is a right and neither is guaranteed. There is no general clawback. For the chain-selection context that prevents these errors in the first place, see the multi-chain stablecoin strategy.

Compliance and wallet-screening holds

A confirmed-clean payment can still stall on the screening leg, and this leg can hold either direction. The compliance-stack article is the deep dive; here, only the failure-handling view.

Sanctions / wallet-screening holds. Address screening checks a counterparty wallet against sanctions lists (such as the OFAC SDN list) before accepting a transaction, including indirect exposure several hops back, and transaction-monitoring (KYT) screening runs on in-flight transfers. Because sanctions lists update frequently, an address that was clean yesterday can be flagged today — which is why a hold can appear mid-flow on a counterparty you have transacted with before. See chain analysis for the concept.

Travel-rule data gaps. Above applicable thresholds, originator and beneficiary information must travel with the transfer; a missing or malformed field can park a transfer pending the data. See travel rule. Resolution for both: this is the provider’s (or your) compliance function — supply the missing data or await the review outcome. Do not retry the on-chain leg to “force” it through; that risks a duplicate send against a hold that is about data, not delivery.

Depeg, liquidity, and conversion exposure

Frame this strictly operationally. This is not investment advice, and nothing here predicts whether any coin will or will not hold its peg.

The on-chain leg is fast and cheap; the conversion legs carry the exposure. Two operational risks live here:

• Quote-to-settlement timing gap. The rate you were quoted and the rate at which the conversion actually settles are separated by a window. If the conversion leg moves in that window, the realized fiat differs from the quote — a mark-to-market on the conversion leg. Capture the quote ID and timestamp so a “wrong amount” complaint can be diagnosed as a timing gap rather than a system error.
• Thin off-ramp liquidity. In some currencies and corridors, the off-ramp side has limited depth. A large conversion can move the effective rate (slippage) or hit a provider limit, delaying or partially filling the payout.

Treat a conversion gap as an exposure to manage, not a defect to “fix.” The cost mechanics of these legs are covered in the on/off-ramp economics article — this runbook only flags it as a failure-diagnosis category so it is not misread as a blockchain or provider bug.

Reconciliation and settlement implications

A ramp transaction has to reconcile across three records, and a break is just a leg that did not match. This mirrors the three-way match in the PSP reconciliation runbook, adapted for the on-chain leg.

• The fiat leg — the bank credit (on-ramp funding) or debit (off-ramp payout), matched by the bank reference.
• The on-chain leg — the stablecoin transfer, matched by the transaction hash on the relevant chain. The tx hash is the on-chain analogue of a bank reference: it is the one identifier that independently proves the transfer happened, to whom, and for how much.
• The provider’s record — the session or reference ID tying the fiat leg and the on-chain leg together.

A two-way match (your ledger vs the provider) has the same blind spot as in card settlement: the provider can report a transfer that the chain or the bank never actually completed. Only matching all three closes the loop. For the fiat-side settlement-file mechanics, the Stripe/Adyen settlement reference is the field-level companion. See reconciliation and settlement for the terms.

Customer-support messaging guidance

PaymentBrief operator guidance. The single highest-risk thing a support agent can do is imply a confirmed on-chain transfer is reversible. The say / do-not-say table:

Provider / bank / treasury escalation checklist

PaymentBrief operator guidance — escalate to the owner of the failing leg, not blindly to the provider.

• Fiat bank leg → the bank (yours or the customer’s). Escalate with the bank transfer reference, value date, amount, and sender/beneficiary names. Used for: deposit not credited, payout not received, name/reference mismatch, returned transfer.
• Ramp-provider leg → the provider’s support / account team. Escalate with the provider session/reference ID, the session status, and the rejection reason. Used for: rejected sessions, unsupported funding method or destination, stuck fulfillment_processing.
• Compliance/screening leg → the provider’s compliance function (or yours). Escalate with the screened address and any travel-rule fields already collected. Used for: sanctions/wallet-screening holds, travel-rule data gaps. Do not retry the chain leg while a screening hold is open.
• Blockchain leg → no one owns the network. There is no escalation target for a confirmed on-chain transaction. Read the tx hash on a block explorer; if it is confirmed to the wrong address/chain, move to the goodwill/custodial path (which may mean escalating to the exchange that controls the destination), never to “reverse it.”
• Treasury/liquidity leg → treasury and/or the provider. Escalate with the quote ID, timestamp, requested vs filled rate, and limit state. Used for: expired quotes, slippage, limit breaches, thin-liquidity delays.

Evidence and logging checklist

PaymentBrief operator guidance. Capture this before escalating — reconstructing it after the fact is slow and sometimes impossible. This is the irreducible evidence set:

• Transaction hash — the on-chain proof; the single highest-leverage field for any chain-leg issue.
• Chain / network — which blockchain (and, where relevant, native vs bridged token), so the hash is read on the right explorer.
• Source and destination address — both ends of the on-chain transfer.
• Amount and token — the asset and quantity, not just a fiat figure.
• Provider session / reference ID — the key that ties the fiat and on-chain legs together in the provider’s system.
• Fiat bank reference — the bank-side transfer reference and value date for the fiat leg.
• Quote ID + timestamp — for any conversion-rate dispute.
• Timestamps — initiation, broadcast, confirmation, and bank value date, in a consistent time zone.

If your system logs the tx hash and provider session ID at the moment of each transfer, most investigations become a lookup rather than a forensic exercise.

Monitoring and prevention controls

PaymentBrief operator guidance — most ramp failures are cheaper to prevent than to handle.

• Pre-send address and network validation. Validate the destination address format for the intended chain and confirm the token is supported on that network before broadcasting. This is the single control that prevents the unrecoverable wrong-chain/wrong-address class.
• Test transfers. For a new counterparty or corridor, send a small test amount and confirm receipt before moving the full value.
• Screen before send. Run wallet/sanctions screening on the destination address before initiating, so a screening hold surfaces pre-send rather than mid-flow.
• Liquidity and limit monitoring. Watch off-ramp liquidity and provider limits for your corridors so a large conversion does not hit slippage or a limit breach unexpectedly.
• Supported-asset allowlists. Maintain an allowlist of (token, chain) pairs your operation supports, and reject anything off-list at the application layer rather than discovering it on-chain.

Common mistakes

• Promising a chargeback or reversal. There is none. A confirmed transfer is final; a return is a new transfer the counterparty must agree to.
• Not capturing the transaction hash. Without the hash and chain, the on-chain leg cannot be investigated — and after the fact the customer may no longer have it.
• Assuming all chains are interchangeable. A token native to one network is not automatically usable on another; cross-chain movement is a deliberate burn-and-mint, not an automatic equivalence. Treating chains as fungible is how wrong-chain sends happen.
• Treating a depeg or conversion gap as a system error. The quote-to-settlement gap and thin liquidity are operational exposures on the conversion leg, not bugs to file against the platform.
• Retrying a “stuck” transfer before confirming on-chain status. A transfer that is merely unconfirmed is in-flight, not failed. Resending it risks a duplicate send — paying twice. Read the hash first.

Related references

• Stablecoin on/off-ramp operations: where the cost advantage gets eaten — the economics neighbor; provider landscape and corridor cost math.
• Stablecoin settlement-loop anatomy — the full flow map this runbook abridges.
• Stablecoin compliance stack: travel rule and chain analysis — the screening-leg deep dive.
• PSP reconciliation failure runbook — the three-way-match parallel for the fiat and provider records.
• The working-capital cost of payments — why settlement timing on the fiat legs has a cash-flow cost.

Scope note

• Six legs, kept distinct: (a) the fiat bank leg, (b) the ramp-provider leg, (c) the blockchain transaction leg, (d) the wallet/compliance screening leg, (e) the treasury/liquidity leg, and (f) PaymentBrief operator guidance — the say/do-not-say, escalation, evidence, and prevention checklists are this site’s recommendations, not vendor behavior.
• No investment or legal advice. Depeg, liquidity, and conversion content is framed as operational exposure on the conversion leg only. Nothing here predicts a peg outcome or recommends a holding, and nothing here is legal advice on sanctions or compliance obligations.
• Irreversibility and no-chargeback, stated plainly. On-chain transfers are final once confirmed; there is no chargeback and no general clawback; a wrong-chain or wrong-address send is generally unrecoverable, and recovery (if any) is counterparty-goodwill or custodial-only and never guaranteed. A “refund” is a new transfer, not a reversal.
• Gated provider docs not relied on. API-first ramp providers such as Transak and Bridge.xyz do not publicly document their error-code tables to the field level, so this runbook describes failure categories and uses Stripe’s public onramp session taxonomy as one illustrative example. Confirm exact statuses and error codes against your own ramp provider.
• Vendor behavior varies. Session-state names, screening thresholds, refund mechanisms, and supported (token, chain) pairs differ by provider and change over time. Confirm against current provider documentation before building on any specific behavior.