Parse the decline code from the PSP response and classify it: soft decline (retry may succeed — e.g., insufficient funds, temporary hold) vs hard decline (do not retry — e.g., card blocked, fraud flag, do-not-honor, stolen card reported); respond differently to each class.
For soft declines: attempt at most one retry after a short delay (at least 30–60 seconds); use the same idempotency key; if the retry also fails, escalate to the human — do not loop.
For hard declines: stop immediately, do not retry; surface a structured error to the agent's orchestrator with the decline classification, the task that was in progress, and the specific payment step that failed.
Preserve the task state so the human can inspect it: what was being purchased, from which merchant, at what price, and at which step in the checkout flow did the decline occur; this context is required for the human to decide whether to use a different payment method and re-queue.
Notify the human principal via a durable channel with the decline reason in plain language (not raw PSP codes), the task context, and a clear call to action: update payment method, increase spending limit, or approve a manual alternative.
Roll back any side effects that occurred before the payment step: abandon the cart if it holds reserved inventory, cancel any pending order in a pre-payment state; do not leave orphaned sessions or reservations on the merchant's platform.
Known gotchas
Some PSPs return ambiguous decline codes (generic_decline, do_not_honor) for both fraud blocks and temporary issues; treating all generic declines as hard stops is the safer default — an unnecessary human escalation is less harmful than a card being blocked for repeated unauthorized attempts.
Cart and checkout session state often expires within minutes of a decline — if the human takes 30 minutes to respond and then re-authorizes, the agent may need to rebuild the cart from scratch rather than resuming from the decline point; design task state to support full restart, not only resume.
A decline mid-checkout may have already charged a prior step (e.g., a deposit or partial payment succeeded before the main charge declined on a split-payment flow); ensure rollback logic accounts for partial captures that may require explicit reversal, not just cart abandonment.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp