What to do when a blockchain payment goes wrong: a 6-step incident playbook

When a blockchain payment goes wrong, stop sending, find which leg the money is on (wallet, chain, provider, or bank), classify the incident, contain it, resolve it with the right counterparty, and reconcile. Most damage comes from blind retries and missed deadlines, not from lost funds. A written playbook turns a panicked afternoon into a 30-minute routine.

Blockchain payments fail in fewer places than wires, but they fail differently. The hub guide on blockchain payments vs crypto payments covers how the rails work. This page is for the moment something already broke.

Key takeaways

• Pause first. A retry without an idempotency key is how one failed payout becomes two sent payouts.
• Locate the money by leg: on-chain transfers are final, bank legs can fail, return, or sit in review.
• A depeg or a network halt is a pricing and timing problem, not usually a lost-funds problem.
• Know your provider's refund rules before the incident, not during it.
• Close every incident with a reconciliation and one change to limits, routing, or monitoring.

Definition: A blockchain payment incident is any payment that does not reach its expected end state on time: stuck in processing, held for review, failed, returned, sent to the wrong destination, sent twice, or exposed to a stablecoin price move while in flight.

What counts as an incident in a blockchain payment?

Anything that leaves a payment outside its expected state or timing. In practice, seven incident types cover almost every case a payments team sees.

The list matters because each type has a different owner and a different fix. Mixing them up is the most common way an incident drags on.

What are the six steps of the playbook?

Stop, locate, classify, contain, resolve, close. Run them in order every time, even for small incidents, so the habit holds when a big one lands.

1. Stop the bleeding. Pause automated retries and new payouts on the affected corridor, network, or recipient. If your system retries on timeouts, make sure every retry sends the same Idempotency-Key, or turn retries off until you know the state.
2. Locate the money. Pull the payout ID, quote ID, transaction hash, and any bank reference such as a UETR for wires. Read the current status and the tracking fields. You want one sentence: "the funds are on leg X, with party Y."
3. Classify and assign an owner. Pick the incident type from the table above and a severity. One payout to one contractor is low. A halted network with 300 payouts in flight is high. Name one owner.
4. Contain. Cap exposure while you work. Hold new payouts to the affected recipient, switch new payments to another network, lower internal limits, or stop holding stablecoin balances overnight during a depeg.
5. Resolve with the right counterparty. That is the provider's support team for stuck or held payouts, the compliance team for a request for information, the recipient for wrong bank details, and nobody for a confirmed transfer to a wrong wallet address you don't control.
6. Close and learn. Reconcile your ledger against the provider's final statuses, tell affected recipients what happened, and write down one change to limits, routing, monitoring, or onboarding.

Steps 1 and 2 should take minutes. If they take hours, the gap is in your logging, not in the blockchain.

How do you find where the money is?

Map the payment to its legs and check the evidence for each one. A blockchain payment has up to five legs, and only one of them is truly irreversible.

The guide to tracking an off-ramp payout lists the reference each rail gives you. The party map in who is involved in a blockchain payment shows who is responsible at each step.

What should be in a blockchain payment risk register?

A register lists each risk, how it shows up, what makes it likelier, how you reduce it, and who owns it. Build it before the first incident and review it quarterly.

The depeg row deserves its own page. Stablecoin depeg risk for payment companies covers limits in detail.

What happened in real blockchain payment incidents?

Two public incidents show the pattern: the money was not lost, but timing and price moved fast. Both are well documented by primary sources.

USDC, March 2023. Silicon Valley Bank failed on Friday, March 10, 2023. That evening Circle announced it could not withdraw $3.3 billion of USDC reserves from SVB, around 8% of total reserves, and at its trough USDC traded at 86 cents, according to a December 2025 Federal Reserve note. On March 12, the Treasury, the Federal Reserve, and the FDIC announced that all SVB depositors would have access to their money the next day, and the peg recovered.

The lesson for payments: anyone holding USDC over that weekend carried price risk, while anyone who converted at a locked quote did not.

Solana, February 2024. On February 6, 2024, at 09:53 UTC, Solana mainnet block finalization halted. Consensus resumed at 14:55 UTC, about five hours later, per Solana's own outage report. Transactions sent during the halt simply didn't confirm.

The lesson: a halt is a timing incident. The fix is to stop new submissions, avoid duplicates, and route new payments over another network.

What happens to the funds when a payout fails?

It depends on the provider's rules and the rail, so read them before you need them. A failed bank leg does not always mean an automatic refund.

At BlindPay, a payout moves through processing, can pass through on_hold, and ends as completed, failed, or refunded, as listed in the payouts docs. The payout statuses guide explains each one.

BlindPay operates as a non-custodial payment processor for payout flows from customer-controlled wallets: you authorize the exact amount and BlindPay executes that single transaction. If a payout cannot be delivered after the stablecoins are collected, BlindPay refunds them to the quote's refund wallet, or to the sending wallet when none is set. On Pix and other non-USD local rails the refund is automatic, while USD payouts and payouts whose review times out are refunded after an operator review.

Two practical rules follow. A payout that reaches failed or sits in review does not refund itself, so contact support@blindpay.com instead of waiting. And a request for information on a held transaction has a short clock: the on-hold transactions guide says a transaction may be refunded if the request isn't answered within 24 hours.

How do you avoid making the incident worse?

Don't retry without idempotency, don't send a "test" payment to the same broken destination, and don't promise the recipient a time you can't see. These three mistakes turn one incident into three.

• Retries. Send the same Idempotency-Key on every retry of a mutating call. BlindPay replays the original response instead of creating a second payout, and keeps the key for 24 hours, per the idempotency docs. The idempotency keys guide shows the pattern.
• Webhooks. If your webhook handler was down, replay missed events instead of guessing state. BlindPay's webhook docs describe a hosted portal where a teammate can browse delivery attempts and replay events.
• Recipient messages. Tell the recipient which leg the payment is on and when you'll update them next. Skip estimates you can't verify.

The most common root causes are in common stablecoin payout mistakes: wrong network, expired quotes, and bad bank details.

How does BlindPay help during an incident?

BlindPay gives you the state of every payout in one place, so step 2 of the playbook is an API call instead of a hunt. The rest of the playbook stays yours.

• Payout statuses plus tracking sub-statuses for the payment, transaction, and liquidity steps.
• Signed webhooks for every state change, with a hosted portal to replay deliveries.
• Idempotency-Key support on mutating requests, so retries can't double-send.
• SWIFT (POBO/COBO) payouts carry a UETR once the wire is confirmed, so every bank in the chain can trace the same payment.
• Nine supported networks, listed in supported chains, so a halt on one network doesn't have to stop new payouts on a corridor.

BlindPay is backed by Y Combinator and handles about $2.5 billion in annualized volume across 100+ countries.

What to do next

Copy the six steps and the risk register into your runbook, name an incident owner, and test the playbook once with a forced failure on a development instance. If you're still choosing a provider, what happens if a stablecoin payment provider fails covers the provider-side risk.

Read the BlindPay payouts docs to map every status and refund path into your playbook before your next payout run.

To plan for these incidents before they happen, use the cross-border stablecoin payments risk register.