Skip to content
EncryptTechBD
Home Industries Our Work Blog Pricing About Contact Discuss Your Project
বাংলা (BN)
Payments & Reconciliation 6 min read

Payment failure recovery workflow: a step-by-step guide

How to design a payment failure recovery workflow that classifies failures, avoids double charges, reconciles with providers and closes the loop with customers.

E
EncryptTechBD · 0 comments
Person working on a laptop
Photo: Matt Moloney / StockSnap

A payment failure is not one event. It is a sequence: the customer presses pay, the request leaves your system, the provider returns a response, a webhook may arrive later, and the bank settles the money on another day. When those steps disagree, the customer sees a failed order while the money has already left their account.

A recovery workflow exists to make that sequence predictable. The goal is not to eliminate failures. The goal is to detect them quickly, classify them correctly, resolve them without double charging, and give the customer a clear answer.

Prerequisites

Do not start with a support script. Start with the system conditions that make a script possible.

  • A payment state machine: initiated, authorised, captured, failed, cancelled, refunded and disputed, with allowed transitions.
  • Idempotency keys: every payment attempt carries a unique key so a retry cannot create a second charge.
  • A ledger: an append-only record of payment events, separate from the order status.
  • Webhook verification: signature checks and replay protection, with a queue for delayed events.
  • A runbook: named roles for support, finance and engineering, plus the provider's escalation contacts.
  • A test environment: a way to simulate declines, timeouts, duplicate webhooks and refunds.

Step 1: Detect the failure

Detect from three sources: the synchronous response, the webhook and the reconciliation report. Do not rely on the browser redirect. Customers close tabs, networks drop and mobile browsers behave unpredictably. The server-to-server response is more reliable than the browser, and the settlement report resolves the rest.

Create an exception record for every payment that is not in a terminal state after a defined interval. That record should include the order ID, payment attempt ID, provider reference, amount, currency, timestamp and current state.

Step 2: Classify the failure

Classification determines the correct action. A useful set of categories is:

  • Hard decline: the issuer or provider says the payment method cannot be used. Do not retry the same method.
  • Soft decline: insufficient funds, temporary issuer rule or velocity limit. A later retry or another method may work.
  • Timeout or unknown: no definitive response. The payment may have succeeded. Reconcile before doing anything else.
  • Duplicate request: the same idempotency key or provider reference appears twice. Suppress the second charge.
  • Configuration or integration error: wrong merchant credentials, currency mismatch or malformed request.
  • Customer cancellation: the customer abandoned or cancelled before completion.

Step 3: Freeze and preserve evidence

Before retrying, capture the request and response payloads, the provider reference, the HTTP status, the error code and the timestamp. Mask sensitive data such as card numbers and personal details. This evidence is what lets support answer the customer and what lets engineering find the cause.

Step 4: Reconcile with the provider

Pull the provider's transaction status and the settlement or payout report. Match on the provider reference and the amount, not on the order number alone. If the provider shows a successful capture and your system shows a failure, the order is paid and the customer should not be asked to pay again.

Run reconciliation at least daily, and more often for high-volume periods. A mismatch that sits for a week becomes a refund dispute.

Step 5: Choose the recovery path

Use a decision rule rather than a support agent's judgement:

  1. Paid but order failed: repair the order or refund. Never ask for a second payment.
  2. Unknown: hold the order, reconcile, then decide. Do not retry automatically.
  3. Soft decline: offer a retry after a defined interval or a different payment method.
  4. Hard decline: ask for another method and explain the decline without guessing the bank's reason.
  5. Duplicate: void the duplicate authorisation or refund the extra capture.
  6. Configuration error: stop customer-facing attempts, fix the integration and replay the affected queue.

Step 6: Retry safely

Automatic retries should be limited, spaced and idempotent. Retry only soft failures, use exponential backoff, cap the number of attempts, and stop immediately if the provider returns a definitive failure. Every retry must reuse the original idempotency key or a deliberate new key with a clear reason.

For mobile financial services and card payments in Bangladesh, confirm the provider's rules on retry windows and duplicate detection. Providers differ, and a retry that is safe with one may be treated as a new transaction by another.

Step 7: Communicate with the customer

Send one clear message that states what happened, what you are doing, what the customer should do and when they will hear from you. Avoid blaming the bank. Avoid promising a refund timeline you cannot control. If the payment is in an unknown state, say that you are verifying it and give a specific follow-up time.

For high-value orders, a phone call is often faster than email. Give support a template with fields for the amount, the reference, the next step and the owner.

Step 8: Update the ledger and the order

Write the resolution as a new event; do not overwrite history. The order status, payment status and finance ledger should agree after the update. If a refund is issued, record the refund reference and the expected settlement date. If the order is cancelled, release inventory and notify fulfilment.

Step 9: Close the loop

Tag the root cause, link the incident to the provider if relevant, and review trends weekly. A failure that recurs on one payment method or one device type is a product problem, not a support problem.

Evidence checklist

  • Payment attempt ID, provider reference and idempotency key.
  • Request and response timestamps, status codes and error codes.
  • Webhook payloads with signature verification results.
  • Provider settlement or payout report line.
  • Customer communication log and the resolution decision.
  • Refund or void reference, if applicable.

Common mistakes

  • Retrying an unknown payment before reconciliation, which creates a double charge.
  • Treating the browser redirect as proof of success or failure.
  • Using the order number as the only matching key.
  • Letting support issue refunds without a ledger entry.
  • Ignoring delayed webhooks that arrive after the order has been closed.
  • Measuring success by ticket closure instead of by correct financial outcome.

Metrics to track

  • Percentage of payments resolved within one business day.
  • Duplicate charge count and refunded amount.
  • Payment success rate by method, device and provider.
  • Reconciliation exceptions open for more than 48 hours.
  • Average time from failure detection to customer notification.
  • Repeat failure rate for the same root cause.

Where this fits in our work

If you need a payment flow that can survive failures, start with Commerce Systems. The pricing page explains how we scope integration work. For fraud controls that sit alongside recovery, read how payment fraud monitoring matures.

Sources

Services that deliver this

Want this implemented properly?

Pricing →

Every engagement starts with a written scope. If a requirement is outside it, we quote it separately before starting.

Responses (0)

No comments yet. Add the first one below.

Leave a response

Your email address will not be published. Required fields are marked *.

Keep reading

More field notes