How to monitor failed payments and recover automatically

Classify failures first

Recovery depends on the failure type. A validation error should not be retried. A timeout may need status lookup. A settlement failure may need refund handling. Treating every failure the same creates duplicate payments and support tickets.

Failure categories

• Validation failure: malformed request, unsupported token, or bad address.
• Policy failure: spending limit, daily cap, or app-level allowlist.
• Funds failure: insufficient balance.
• Network failure: timeout or temporary upstream error.
• Settlement failure: transaction failed after funds were reserved.
• Notification failure: payment succeeded but webhook delivery failed.

Failure record

type PaymentFailure = {
  paymentId: string | null;
  idempotencyKey: string;
  category: "validation" | "policy" | "funds" | "network" | "settlement" | "notification";
  retryable: boolean;
  lastError: string;
  nextRetryAt: string | null;
};

Recovery rules

• Do not retry validation or policy failures automatically.
• Retry network failures with the same idempotency key.
• Check payment status before resubmitting uncertain commands.
• Send notification failures to a webhook retry queue.
• Page humans for settlement failures and refund anomalies.

Operator dashboard

Operators need a small set of actions: retry notification, check status, mark as acknowledged, export payload, and open the related wallet or user. Avoid a dashboard that only shows red errors without a next step.

What to alert on

• Spike in failed payments per minute.
• Settlement failures above zero.
• Webhook retry queue age above threshold.
• Pending payments stuck longer than expected.
• Repeated failures for the same wallet or recipient.