How to Diagnose Payment Failures

V3 How to Diagnose Payment Failures: A Step-by-Step Troubleshooting Guide “Payment failed” is a symptom, not a diagnosis A failed payment can result from an issuer decline, merchant-side risk control, authentication problem, malformed request, provider outage, uncertain timeout, expired credential, or post-authorization reconciliation issue. The correct fix depends on identifying which layer produced the failure and confirming the payment’s authoritative status before retrying or asking the customer to pay again. Quick diagnostic sequence 1. Determine whether an issuer authorization was attempted. 2. Confirm whether the current status is approved, declined, pending, unknown, or unavailable. 3. Classify the event as an authorization decline, merchant-side block, technical failure, authentication failure, or post-authorization issue. 4. Segment the affected transactions by provider, route, issuer or IIN/BIN range, geography, authentication outcome, and time period. 5. Apply the response recommended by the network, acquirer, PSP, or authentication provider. 6. Confirm the final provider status and internal ledger state before communicating the outcome or creating another charge. Start with the payment chain, not the customer-facing symptom A card payment can involve several systems: Customer → Merchant application → Gateway or PSP → Processor or acquirer → Card network → Issuer

Authentication systems, token services, fraud tools, and routing layers may also participate. Capture, clearing, settlement, payout, and reconciliation occur later and can fail independently of authorization. Use elimination rather than assumption. Start with logs, request identifiers, provider records, authentication results, and network or acquirer response data. A timeout shown to the customer does not prove that authorization failed. The request may have completed even though the customer or merchant did not receive the final response. Before sending another non-idempotent payment request, retrieve the provider’s authoritative transaction status or use a provider-supported idempotency or deduplication mechanism. HTTP standards caution against automatically retrying non-idempotent requests after a communication failure unless the client can determine that the original request was not applied or can otherwise make the operation idempotent. [1] Step 1: Collect evidence before forming a theory Read the PSP or gateway record first. Locate the payment attempt using the provider’s transaction ID, request ID, merchant reference, or deduplication identifier. Work from the provider’s recorded status and response data rather than the generic message displayed at checkout. Capture the full context for each attempt. A response code alone rarely explains the whole event. Record, where available: * Transaction ID, provider request ID, and merchant reference

* Timestamp, processing route, acquirer, and processor * Issuer Identification Number or Bank Identification Number (IIN/BIN) range * Issuing country, network, funding type, card type, amount, and currency * Authentication status and EMV 3-D Secure result * Provider-normalized response and raw network or acquirer response * Attempt number and whether the request was customer-initiated or merchant-initiated * API latency, HTTP status, and provider error type * Idempotency key or another deduplication identifier Normalize response categories across providers. Different PSPs can expose the same underlying outcome with different labels. A canonical internal mapping should preserve each provider’s raw response while assigning a consistent internal category, such as issuer decline, merchant risk block, authentication failure, technical failure, pending or unknown outcome, or post-authorization issue. Instrument API calls. Record request IDs, latency, HTTP status, provider error type, and deduplication identifiers. An idempotent design ensures that repeating an operation has the same intended effect as performing it once, which is important when a communication failure leaves the original outcome uncertain. [1] Step 2: Classify the failure before acting Do not apply one recovery action to every unsuccessful attempt. Failure category What is happening Recommended response Potentially retryable authorization decline

The issuer or provider returned a temporary or remediable outcome, such as insufficient funds, authentication required, temporary issuer unavailability, or another response for which network or provider guidance permits another attempt. Follow the network advice signal and PSP guidance. The next step may be authentication, corrected information, an updated credential, another method, or a later retry. Non-retryable authorization decline The issuer, network, or provider indicates that the same credential or authorization should not be submitted again, such as a lost or stolen card, closed account, invalid account, or explicit do-not-retry instruction. Do not resubmit the same authorization unchanged. Follow provider guidance and request corrected details, an updated credential, or another method where appropriate. Merchant-side risk block The merchant’s fraud tool, PSP risk layer, velocity rule, blocklist, or manual-review policy stopped the transaction before issuer authorization. Identify the rule or model decision that fired. Review false-positive indicators before changing the control. Technical or integration failure The request was malformed, timed out, failed before authorization, or produced an uncertain result. A problem may also occur after authorization if the merchant fails to process the provider notification correctly. Fix the integration or operational process. For uncertain outcomes, retrieve the provider’s authoritative status before retrying. Authentication failure

EMV 3DS authentication could not be completed or was unsuccessful because of a failed challenge, timeout, unavailable issuer Access Control Server, unsupported flow, or another authentication result. Investigate the authentication flow separately from card authorization and use the 3DS transaction status, challenge result, and error data. Post-authorization capture, settlement, or reconciliation issue Authorization may have succeeded, but capture, clearing, settlement, payout, or internal ledger records do not match. Treat it as a capture, data, timing, settlement, or ledger investigation—not as an issuer decline. Visa groups authorization response codes into categories that determine whether a reattempt is prohibited or permitted and advises merchants to obtain retry information through their acquirers and processors. [2] Mastercard gateway documentation likewise returns recommendations such as resubmit later, authenticate the payer, use updated payment details, use another payment method, or abandon the order; it also documents Merchant Advice Codes for failed recurring transactions. [3][4] EMVCo explains that EMV 3-D Secure exchanges transaction, payment-method, and device information between the merchant and issuer to authenticate the consumer. Authentication outcomes should therefore be analyzed separately from the subsequent authorization response. [5][6] A useful metric check

For this guide, authorization rate means approvals among requests submitted for authorization. End-to-end payment success rate includes attempts that fail or are blocked before issuer authorization. These metrics diagnose different layers. A merchant-side risk block can lower end-to-end payment success without lowering issuer authorization rate because the request never reached the issuer. Step 3: Segment before concluding Aggregate results can hide concentrated problems. Analyze failures and authorization outcomes by: * Acquirer, processor, PSP, and route * Issuer and IIN/BIN range * Issuing country and customer region * Card network, funding type, and card type * Transaction amount and currency * Customer-initiated versus merchant-initiated transaction * Authentication result * Provider and network response category * First attempt versus later attempt * Time period, deployment, and configuration changes Use statistically meaningful comparisons. A sudden increase in failures for one route, issuer group, authentication result, or country can justify a targeted investigation. Small segments and short time windows can produce misleading fluctuations, so review sample sizes and confidence before changing routing or fraud rules. Common payment-failure root causes Card- and issuer-level causes

Examples include insufficient funds, invalid or replaced credentials, closed accounts, card controls, issuer risk decisions, or authentication requirements. Diagnose these using the provider’s normalized response, any available raw response or advice signal, and the associated authentication data. Merchants cannot control issuer policy, but accurate transaction and authentication data can help issuers evaluate the request. Technical and integration causes Gateway or PSP timeouts. A timeout creates an uncertain outcome unless the provider confirms that the request was not processed. Retrieve the transaction status before creating another attempt. Duplicate requests. A customer may submit twice, a client may retry after a connection failure, or an internal job may repeat a request. Use provider-supported idempotency controls and internal deduplication to prevent duplicate operations. [1] Webhook or notification failures. Event-delivery systems may retry when a subscriber does not acknowledge receipt, and ordering may not be guaranteed. Microsoft Azure Event Grid, for example, documents at-least-once delivery and explicitly states that event order is not guaranteed. Handlers should verify signatures where supported, record event IDs, process events idempotently, and retrieve current object state when ordering matters. [7]

Misconfigured merchant accounts or routes. A merchant account, MID, currency, entity, or route may be ineligible or incorrectly configured for the transaction. Compare the failed segment with known-good routes and confirm the configuration with the PSP or acquirer. Expired or single-use tokens. Some checkout, authentication, or payment tokens are session-bound, single-use, or time-limited. Confirm the token type and lifecycle in the provider’s documentation before assuming that the underlying card credential failed. Merchant-side risk blocks A merchant or PSP risk system can reject a legitimate customer before issuer authorization. Diagnose this by confirming whether an issuer authorization was attempted and reviewing the exact rule, model score, or manual-review outcome. Track observable false-positive indicators such as successful retries with unchanged customer identity, manual-review approvals, support contacts, and later successful purchases. Recurring and stored-credential causes Recurring payments have additional failure modes: * The stored credential expired, was replaced, or became invalid. * Required stored-credential or merchant-initiated transaction indicators were missing or incorrect. * The renewal amount, timing, or merchant information differed materially from prior activity. * Authentication or customer action was required. * The retry strategy did not follow provider or network advice.

Do not assume that card expiration is always the dominant cause for every merchant. Measure the portfolio’s actual response categories. Use network tokenization and credential-updater services where supported, and ensure that recurring and merchant-initiated transactions are submitted with the required indicators and customer agreement. Retry timing should be based on the response category, provider guidance, network rules, customer agreement, and prior attempt history. Repeating a non-retryable authorization or retrying too frequently can create costs and compliance risk; waiting too long can also reduce recovery. There is no universal schedule that is optimal for every merchant. [2][3][4] Capture, settlement, and reconciliation causes Timing differences. Authorization, capture, clearing, settlement, and payout occur on different schedules. A record can be pending without being failed. Duplicate postings. The same internal event may be recorded twice because of non-idempotent processing or duplicate notifications. Missing or unmatched entries. A provider settlement line, bank deposit, payout, refund, fee, or internal ledger entry may not have a matching record. Amount and currency differences. FX conversion, fees, partial captures, refunds, reversals, and rounding can create legitimate differences that must be reconciled using provider and bank records.

The key question is where the discrepancy first appears. A problem at checkout or authorization belongs to a different investigation than a mismatch discovered during capture, settlement, payout, or ledger reconciliation. Build a repeatable diagnostic capability Centralize before analyzing. Bring PSP, acquirer, authentication, risk, and internal ledger data into a normalized model while preserving raw provider fields for audit and troubleshooting. Layer dashboards by depth. Use an executive view for end-to-end payment success, authorization rate, volume, and financial impact; an operational view by provider, route, market, and payment method; and a diagnostic view for response codes, latency, authentication outcomes, retries, and technical errors. Alert on deviations and absolute limits. Static thresholds can detect severe failures, while baseline or anomaly monitoring can identify segment-level changes hidden in aggregate results. Use minimum sample sizes and confidence controls to avoid reacting to normal statistical noise. Track economic effects alongside operational performance. Monitor processing cost, interchange and scheme fees, FX, retry costs, fraud loss, chargebacks, refunds, and support impact—not only authorization rate. Payment-failure diagnostic runbook 1. Pull the authoritative record: PSP or gateway transaction, request ID, raw and normalized response, authentication result, HTTP status, or reconciliation exception.

2. Determine whether issuer authorization was attempted and whether the outcome is approved, declined, pending, unknown, or unavailable. 3. Classify the event: potentially retryable decline, non-retryable decline, merchant-side block, technical or integration failure, authentication failure, or post-authorization issue. 4. Segment the data by provider, route, issuer or IIN/BIN range, geography, authentication result, response category, transaction type, and time period. 5. Check for clustering and recent changes. Compare affected segments with known-good segments and review deployments, routing changes, fraud-rule changes, credential changes, and provider incidents. 6. Match the response to the category. Follow provider and network advice for authorization retries; fix integrations for technical failures; investigate authentication separately; tune risk controls using false-positive evidence; and treat settlement discrepancies as capture, timing, or ledger issues. 7. Confirm the outcome. Before telling the customer that a payment failed or creating another charge, verify the provider’s current status and the merchant’s internal ledger. 8. Close the loop. Feed verified findings into monitoring, routing, retry policies, authentication data quality, fraud controls, and operational documentation. Frequently asked questions What does “payment failed” mean?

It means the attempted payment did not reach a confirmed successful outcome in the merchant’s flow. The cause may be an issuer decline, merchant risk block, authentication issue, technical failure, unknown timeout result, or post-authorization problem. How do you diagnose a failed payment? Start with the PSP or gateway’s authoritative transaction record, determine whether issuer authorization was attempted, classify the failure, segment similar events, and follow the network or provider’s recommended action. How can I tell whether a payment was declined by the issuer or blocked by the merchant? Confirm whether the request reached issuer authorization. An issuer decline normally has a network or acquirer response. A merchant-side block appears in the merchant or PSP risk decision and may have no issuer response because authorization was never attempted. Should a merchant retry a failed payment? Only when the response category, network advice, PSP guidance, customer agreement, and attempt history permit it. Do not apply one retry schedule to every decline, and do not resubmit an uncertain timeout until the current status is known. What should a merchant do after a payment timeout? Treat the outcome as unknown until the provider confirms otherwise. Retrieve the transaction status using the request or merchant reference and use idempotency or deduplication controls before creating another attempt. What is the difference between an authorization failure and a settlement failure?

An authorization failure occurs before the issuer approves the transaction. A settlement or reconciliation issue occurs after authorization, when capture, clearing, payout, bank deposits, or ledger records do not match. Sources [1] IETF / RFC Editor, RFC 9110, “HTTP Semantics,” Section 9.2.2, Idempotent Methods. [2] Visa, “Authorization Response Code Update, Alignment and Reminders,” Merchant Business News Digest, April 2024. [3] Mastercard Payment Gateway Services, Authorize API documentation and gateway recommendations. [4] Mastercard Payment Gateway Services, recurringPaymentAdvice / Merchant Advice Code documentation. [5] EMVCo, “EMV 3-D Secure,” official overview. [6] EMVCo, “Improving Risk Analysis and Frictionless Flow—Technical Features,” EMV 3-D Secure White Paper. [7] Microsoft Learn, “Azure Event Grid message delivery and retry.” Methodology note This guide uses public technical documentation from payment networks, standards bodies, and non-PSP technology providers. Provider-specific behavior can differ, so merchants should follow their own PSP, acquirer, authentication provider, and network requirements. Response codes, retry permissions, token lifecycles, and event-delivery behavior should not be assumed to be identical across providers.

Fact-checked, source-supported, and optimized for merchant search intent Recommended title tag How to Diagnose Payment Failures: Causes, Logs & Fixes Meta description Learn how to diagnose failed payments using gateway logs, issuer responses, 3DS results, retry guidance, and reconciliation data. Suggested URL slug /blog/how-to-diagnose-payment-failures Primary query how to diagnose payment failures Related queries payment failure troubleshooting; failed payment diagnosis; payment decline troubleshooting; gateway timeout payment; issuer decline vs gateway error

SEO and publishing recommendations These recommendations are separate from the article copy and are intended for the CMS and publishing workflow. On-page priorities * Use the recommended title tag and a single prominent H1. Google advises descriptive, concise titles and warns against keyword stuffing or repetitive boilerplate. [SEO-1] * Keep the opening definition and quick diagnostic sequence visible without requiring users to open tabs or accordions. This supports fast comprehension and section-level search snippets. * Add a linked table of contents with HTML anchor links to the main steps, root causes, runbook, and FAQs. * Use descriptive H2 headings that match real troubleshooting intent: issuer decline, gateway timeout, 3DS authentication failure, merchant risk block, recurring payment failure, and settlement reconciliation. * Add an accurate author byline and a reviewer with demonstrable payments expertise. Link both to profile pages that explain their credentials and experience. * Add a “Last reviewed” date only when the technical content has actually been reviewed or updated. * Include one original diagnostic visual, such as a payment-failure decision tree or payment-chain diagram, with descriptive alt text. * Link internally to deeper pages on payment decline codes, authorization-rate optimization, 3D Secure, payment retries, network tokenization, recurring payments, fraud rules, and reconciliation.

* Link outward only when an official technical source directly supports a claim. Keep the numbered source list and connect key claims to the relevant source number in the body. * Use Article or BlogPosting structured data with headline, author, reviewer where supported, datePublished, dateModified, and representative images. Structured data can help Google understand the page, but it does not guarantee a rich result. [SEO-2] Recommended internal-link anchors * payment decline codes and recommended actions * how to improve payment authorization rates * EMV 3-D Secure authentication * payment retry strategy for recurring billing * network tokenization and credential updates * how to reduce false declines * payment reconciliation and settlement * local acquiring and intelligent routing Search-intent coverage to add or preserve The revised article directly answers the informational and operational questions most likely to sit behind searches in this topic: * Why did a payment fail? * How do I troubleshoot a failed payment? * Was the payment declined by the bank or blocked by the merchant? * Should I retry a failed payment? * What should I do after a payment timeout? * Why did 3D Secure fail? * Why did a recurring payment fail? * What is the difference between authorization and settlement failure? Schema recommendation

Use Article or BlogPosting structured data. The FAQ section is valuable for users and long-tail query coverage, but Google has limited regular FAQ rich results mainly to authoritative government and health sites, so FAQPage markup should not be treated as a likely visibility win for a payments company. [SEO-3] SEO sources [SEO-1] Google Search Central, “Influencing your title links in search results.” [SEO-2] Google Search Central, “Article structured data.” [SEO-3] Google Search Central, “Changes to HowTo and FAQ rich results.” [SEO-4] Google Search Central, “Creating helpful, reliable, people-first content.” [SEO-5] Google Search Central, “Control your snippets in search results.”

v2 How to Diagnose Payment Failures “Payment failed” is a symptom, not a diagnosis. The same customer-facing message can reflect an expired credential, an issuer decline, a merchant-side risk block, a malformed API request, an incomplete authentication, or a notification that never reached the merchant. Each requires a different response. This guide presents a systematic way to identify where a payment attempt failed, what evidence to collect, and which action fits the failure type. Start with the chain, not the symptom A card payment can involve several systems: Customer or client → Merchant application → Gateway or PSP → Processor or acquirer → Card network → Issuer Authentication systems, token services, fraud tools, and routing layers may also participate. Capture, clearing, settlement, payout, and reconciliation occur later and can fail independently of authorization.

Use elimination rather than assumption. Start with logs, request identifiers, provider records, authentication results, and network or acquirer response data. A timeout shown to the customer does not prove that authorization failed. The request may have completed even though the customer or merchant did not receive the final response. Before sending another non-idempotent payment request, retrieve the provider’s authoritative transaction status or use a provider-supported deduplication mechanism. HTTP standards caution against automatically retrying non-idempotent requests after a communication failure unless the client can determine that the original request was not applied or can otherwise make the operation idempotent. [1] Step 1: Collect the evidence before forming a theory Read the PSP or gateway record first. Locate the payment attempt using the provider’s transaction ID, request ID, merchant reference, or deduplication identifier. Work from the provider’s recorded status and response data rather than the generic message shown at checkout. Capture the full context for each attempt. A response code alone rarely explains the whole event. Record, where available: * Transaction and provider request IDs * Timestamp and processing route * Acquirer or processor * Issuer Identification Number or Bank Identification Number (IIN/BIN) range * Issuing country, card type, amount, and currency * Authentication status and EMV 3-D Secure result

* Provider-normalized response and raw network or acquirer response * Attempt number and whether the request was customer-initiated or merchant-initiated * API latency and HTTP status * Idempotency key or another deduplication identifier Normalize response categories across providers. Different PSPs can expose the same underlying outcome with different labels. A canonical internal mapping should preserve each provider’s raw response while assigning a consistent internal category, such as issuer decline, merchant risk block, authentication failure, technical failure, pending or unknown outcome, or post-authorization settlement issue. Instrument API calls. Record request IDs, latency, HTTP status, provider error type, and deduplication identifiers. An idempotent design ensures that repeating an operation has the same intended effect as performing it once, which is important when a communication failure leaves the original outcome uncertain. [1] Step 2: Classify the failure before acting Do not apply one recovery action to every unsuccessful attempt. 1. Potentially retryable authorization decline What is happening: The issuer or provider returned a temporary or remediable outcome, such as insufficient funds, authentication required, temporary issuer unavailability, or another response for which network or provider guidance permits another attempt.

Recommended response: Follow the network advice signal and PSP guidance. The next step may be authentication, corrected information, an updated credential, another method, or a later retry. 2. Non-retryable authorization decline What is happening: The issuer, network, or provider indicates that the same credential or authorization should not be submitted again, such as a lost or stolen card, closed account, invalid account, or explicit do-not-retry instruction. Recommended response: Do not resubmit the same authorization unchanged. Follow provider guidance and request corrected details, an updated credential, or another method where appropriate. 3. Merchant-side risk block What is happening: The merchant’s fraud tool, PSP risk layer, velocity rule, blocklist, or manual-review policy stopped the transaction before issuer authorization. Recommended response: Identify the rule or model decision that fired. Review false-positive indicators before changing the control. 4. Technical or integration failure What is happening: The request was malformed, timed out, failed before authorization, or produced an uncertain result. A problem may also occur after authorization if the merchant fails to process the provider notification correctly. Recommended response: Fix the integration or operational process. For uncertain outcomes, retrieve the provider’s authoritative status before retrying. 5. Authentication failure

What is happening: EMV 3DS authentication could not be completed or was unsuccessful because of a failed challenge, timeout, unavailable issuer Access Control Server, unsupported flow, or another authentication result. Recommended response: Investigate the authentication flow separately from card authorization and use the 3DS transaction status, challenge result, and error data.

6. Post-authorization capture, settlement, or reconciliation issue What is happening: Authorization may have succeeded, but capture, clearing, settlement, payout, or internal ledger records do not match. Recommended response: Treat it as a capture, data, timing, settlement, or ledger investigation—not as an issuer decline. Visa groups authorization response codes into categories that determine whether a reattempt is prohibited or permitted, and advises merchants to obtain the necessary retry information through their acquirers and processors. [2] Mastercard gateway documentation likewise returns recommendations such as resubmit later, authenticate the payer, use updated payment details, use another payment method, or abandon the order; it also documents Merchant Advice Codes for failed recurring transactions. [3][4] EMVCo explains that EMV 3-D Secure exchanges transaction, payment-method, and device information between the merchant and issuer to authenticate the consumer. Authentication outcomes should therefore be analyzed separately from the subsequent authorization response. [5][6] A useful metric check * Authorization rate means approvals among requests submitted for authorization. * End-to-end payment success rate includes attempts that fail or are blocked before issuer authorization. These metrics diagnose different layers. A merchant-side risk block can lower end-to-end payment success without lowering issuer authorization rate because the request never reached the issuer.

Step 3: Segment before concluding Aggregate results can hide concentrated problems. Analyze failures and authorization outcomes by: * Acquirer, processor, PSP, and route * Issuer and IIN/BIN range * Issuing country and customer region * Card network, funding type, and card type * Transaction amount and currency * Customer-initiated versus merchant-initiated transaction * Authentication result * Provider and network response category * First attempt versus later attempt * Time period and deployment or configuration changes Use statistically meaningful comparisons. A sudden increase in failures for one route, issuer group, authentication result, or country can justify a targeted investigation. Small segments and short time windows can produce misleading fluctuations, so compare sample sizes and confidence before changing routing or fraud rules. Common root causes Card- and issuer-level causes Examples include insufficient funds, invalid or replaced credentials, closed accounts, card controls, issuer risk decisions, or authentication requirements. Diagnose these using the provider’s normalized response, any available raw response or advice signal, and the associated authentication data. Merchants cannot control issuer policy, but accurate transaction and authentication data can help issuers evaluate the request. Technical and integration causes

Gateway or PSP timeouts. A timeout creates an uncertain outcome unless the provider confirms that the request was not processed. Retrieve the transaction status before creating another attempt. Duplicate requests. A customer may submit twice, a client may retry after a connection failure, or an internal job may repeat a request. Use provider-supported idempotency controls and internal deduplication to prevent duplicate operations. [1] Webhook or notification failures. Event-delivery systems commonly retry when a subscriber does not acknowledge receipt, and ordering may not be guaranteed. Microsoft Azure Event Grid, for example, documents at-least-once delivery and explicitly states that event order is not guaranteed. Handlers should therefore verify signatures where supported, record event IDs, process events idempotently, and retrieve current object state when ordering matters. [7] Misconfigured merchant accounts or routes. A merchant account, MID, currency, entity, or route may be ineligible or incorrectly configured for the transaction. Compare the failed segment with known-good routes and confirm the configuration with the PSP or acquirer. Expired or single-use tokens. Some checkout, authentication, or payment tokens are session-bound, single-use, or time-limited. Confirm the token type and lifecycle in the provider’s documentation before assuming that the underlying card credential failed. Merchant-side risk blocks

A merchant or PSP risk system can reject a legitimate customer before issuer authorization. Diagnose this by confirming whether an issuer authorization was attempted and reviewing the exact rule, model score, or manual-review outcome. Track observable false-positive indicators such as successful retries with unchanged customer identity, manual-review approvals, support contacts, and later successful purchases. Recurring and stored-credential causes Recurring payments have additional failure modes: * The stored credential expired, was replaced, or became invalid. * Required stored-credential or merchant-initiated transaction indicators were missing or incorrect. * The renewal amount, timing, or merchant information differed materially from prior activity. * Authentication or customer action was required. * The retry strategy did not follow provider or network advice. Do not assume that card expiration is always the dominant cause for every merchant. Measure the portfolio’s actual response categories. Use network tokenization and credential-updater services where supported, and ensure that recurring and merchant-initiated transactions are submitted with the required indicators and customer agreement.

Retry timing should be based on the response category, provider guidance, network rules, customer agreement, and prior attempt history. Repeating a non-retryable authorization or retrying too frequently can create costs and compliance risk; waiting too long can also reduce recovery. There is no universal schedule that is optimal for every merchant. [2][3][4] Capture, settlement, and reconciliation causes Timing differences. Authorization, capture, clearing, settlement, and payout occur on different schedules. A record can be pending without being failed. Duplicate postings. The same internal event may be recorded twice because of non-idempotent processing or duplicate notifications. Missing or unmatched entries. A provider settlement line, bank deposit, payout, refund, fee, or internal ledger entry may not have a matching record. Amount and currency differences. FX conversion, fees, partial captures, refunds, reversals, and rounding can create legitimate differences that must be reconciled using provider and bank records. The key question is where the discrepancy first appears. A problem at checkout or authorization belongs to a different investigation than a mismatch discovered during capture, settlement, payout, or ledger reconciliation. Building repeatable diagnostic capability Centralize before analyzing. Bring PSP, acquirer, authentication, risk, and internal ledger data into a normalized model while preserving raw provider fields for audit and troubleshooting.

Layer dashboards by depth. Use an executive view for end-to-end payment success, authorization rate, volume, and financial impact; an operational view by provider, route, market, and payment method; and a diagnostic view for response codes, latency, authentication outcomes, retries, and technical errors. Alert on deviations and absolute limits. Static thresholds can detect severe failures, while baseline or anomaly monitoring can identify segment-level changes hidden in aggregate results. Use minimum sample sizes and confidence controls to avoid reacting to normal statistical noise. Track economic effects alongside operational performance. Monitor processing cost, interchange and scheme fees, FX, retry costs, fraud loss, chargebacks, refunds, and support impact—not only authorization rate. A practical runbook 1. Pull the authoritative record: PSP or gateway transaction, request ID, raw and normalized response, authentication result, HTTP status, or reconciliation exception. 2. Determine whether issuer authorization was attempted and whether the outcome is approved, declined, pending, unknown, or unavailable. 3. Classify the event: potentially retryable decline, non-retryable decline, merchant-side block, technical or integration failure, authentication failure, or post-authorization issue. 4. Segment the data by provider, route, issuer or IIN/BIN range, geography, authentication result, response category, transaction type, and time period.

5. Check for clustering and recent changes. Compare affected segments with known-good segments and review deployments, routing changes, fraud-rule changes, credential changes, and provider incidents. 6. Match the response to the category. Follow provider and network advice for authorization retries; fix integrations for technical failures; investigate authentication separately; tune risk controls using false-positive evidence; and treat settlement discrepancies as capture, timing, or ledger issues. 7. Confirm the outcome. Before telling the customer that a payment failed or creating another charge, verify the provider’s current status and the merchant’s internal ledger. 8. Close the loop. Feed verified findings into monitoring, routing, retry policies, authentication data quality, fraud controls, and operational documentation. Sources [1] IETF / RFC Editor, RFC 9110, “HTTP Semantics,” Section 9.2.2, Idempotent Methods. https://www.rfc-editor.org/rfc/rfc9110.html#section-9.2.2 [2] Visa, “Authorization Response Code Update, Alignment and Reminders,” Merchant Business News Digest, April 2024. https://www.visa.com/en-us/resources/visa-merchant-business-news-digest

[3] Mastercard Payment Gateway Services, Authorize API documentation, gateway recommendations including resubmit later, authenticate, update details, use an alternative method, or abandon the order. https://na.gateway.mastercard.com/api/documentation/apiDocumentation/rest-json/version/64/operation/Transaction%3A%20%20Authorize.html?locale=en_US [4] Mastercard Payment Gateway Services, recurringPaymentAdvice / Merchant Advice Code documentation for failed recurring transactions. https://na.gateway.mastercard.com/api/documentation/apiDocumentation/rest-json/version/54/operation/Transaction%3A%20%20Authorize.html?locale=el_GR [5] EMVCo, “EMV 3-D Secure,” official overview. https://www.emvco.com/emv-technologies/3-d-secure/ [6] EMVCo, “Improving Risk Analysis and Frictionless Flow—Technical Features,” EMV 3-D Secure White Paper. https://www.emvco.com/dynamic/emv-3-d-secure-whitepaper-v2/improving-risk-emv-3-d-secure-whitepaper-v2-analysis-and-frictionless-flow/technical-features/ [7] Microsoft Learn, “Azure Event Grid message delivery and retry.” Documents at-least-once delivery and non-guaranteed ordering. https://learn.microsoft.com/en-us/azure/event-grid/delivery-and-retry Methodology note

This guide uses public technical documentation from payment networks, standards bodies, and non-PSP technology providers. Provider-specific behavior can differ, so merchants should follow their own PSP, acquirer, authentication provider, and network requirements. Response codes, retry permissions, token lifecycles, and event-delivery behavior should not be assumed to be identical across providers.

v1 How to Diagnose Payment Failures "Payment failed" is a symptom, not a diagnosis. The same error message on a checkout page can mean an expired card, a misconfigured merchant ID, a webhook that never fired, or an issuer's fraud model having a bad day — and each of those needs a completely different fix. This guide walks through a systematic way to find out which one you're actually looking at. Start with the chain, not the symptom A payment touches several distinct systems, and a failure can originate at any link: Customer/client → Merchant application → Payment gateway/API → Acquirer → Card network → Issuing bank (and, separately, a settlement/reconciliation layer that runs after authorization and can fail independently of it). The diagnostic discipline is one of elimination: start broad, then drill down through logs, network calls, and gateway data — letting the evidence (decline codes, exceptions, status codes) guide the investigation rather than guessing based on where the error happened to surface. A timeout on the customer's screen, for instance, doesn't tell you the transaction failed — it tells you you don't know what happened, since the charge may have gone through on the issuer's side even if your system never got the confirmation. Step 1: Get the actual data before forming a theory

Read the gateway logs first. Review the logs from your payment gateway for the specific error code or message — "insufficient funds," "card declined," "expired card" — rather than working from the generic failure the customer saw. Capture full context per attempt, not just the response code. A bare decline code rarely tells the full story on its own; log the 3DS outcome, device type, BIN, attempt number, and timestamp alongside it, since root-cause analysis depends on that surrounding context. Normalize response codes if you run more than one processor. Different gateways categorize the same underlying issuer response differently — one might label a transaction a generic gateway error while another calls it an issuer-side decline — and that classification mismatch is a common reason payment teams struggle to isolate the true root cause. Building one canonical mapping layer across providers is what makes cross-PSP analysis possible at all. Instrument the call itself. For technical/API failures, record latency, HTTP response code, decline reason (if any), and the idempotency key hash for every gateway call — this is what turns "it broke sometime this morning" into "it broke at 9:14am on Acquirer B with a 15% latency spike." Step 2: Classify the failure type before you act on it Not every failure is the same kind of failure, and treating them identically is the single most common diagnostic mistake. Category What's happening Diagnostic signal Right response Soft decline

Issuer approved conceptually but flagged a temporary issue (insufficient funds, issuer system unavailable) Retrying later often succeeds Retry on a sensible schedule Hard decline Issuer permanently refused (invalid/expired/stolen card, closed account) Retrying the same card never succeeds Request a new payment method — don't retry Merchant-side fraud block Transaction never reached the issuer at all — your own rules stopped it Shows up in your fraud tool's logs, not the issuer's response Audit the rule that fired; check for false-decline patterns Technical/integration error Gateway timeout, malformed request, webhook never delivered or processed twice HTTP-level errors, missing webhook events, duplicate ledger entries Fix the integration, not the customer's card Authentication failure 3DS challenge failed, OTP mismatch, signature validation failed Explicit 3DS/ACS status in the response Distinct from a card-level decline — check the authentication flow itself Settlement/reconciliation break Authorization succeeded, but a downstream ledger, bank, or payout record doesn't match Discovered in reconciliation, not at checkout Investigate as a data/timing issue, not a declined payment

A useful gut-check: authorization rate (approvals as a share of requests the issuer actually saw) and approval rate (completed payments as a share of everything attempted, including your own blocked transactions) are different numbers — confusing them means you might be diagnosing your own fraud rules as if they were issuer behavior, or vice versa. Step 3: Segment before you conclude anything An aggregate failure rate hides almost everything useful. The same overall approval rate can coexist with a specific, fixable problem sitting one layer down — for example, an overall rate holding steady while "Do Not Honor" codes for one secondary processor in one country climb sharply, pointing to an upstream issuer or fraud-model issue invisible in the top-line number. Before drawing a conclusion, break the data down by: * Acquirer / PSP — one processor can develop a problem while others stay healthy * Issuer and BIN range — a specific card portfolio can be behaving differently from the rest of your volume * Region / issuing country — cross-border and local patterns diverge substantially * Decline/response code — "Do Not Honor" behaves nothing like "Insufficient Funds" * Time — failures that cluster around specific days (payroll dates, card-expiry cycles) point to a customer-side cause; failures that spike suddenly point to a technical or configuration cause

Modern payment-intelligence tooling automates this by continuously benchmarking current performance against historical baselines at the BIN/issuer/acquirer/route level and flagging statistically significant deviations — catching, for instance, a merchant ID that isn't correctly mapped to an acquirer, or transactions being silently routed down the wrong path, before the issue surfaces as a wave of support tickets. Common root causes, in more depth Card- and issuer-level causes. Insufficient funds, an expired or invalid card, a closed account, or the issuer blocking a transaction it perceives as unusual (foreign, high-value, or off-pattern for that cardholder) sit at this level. These are diagnosed from the decline code itself and are largely outside the merchant's direct control — though better transaction data (accurate AVS, CVV, and 3DS context) can influence the issuer's decision. Technical and integration causes. These are diagnosed in your own logs, not the issuer's response, and include: * Gateway timeouts — the transaction takes too long and the gateway doesn't respond in time. * Duplicate requests — a user double-clicks "pay," and the system may block it as a duplicate or, worse, process it twice if idempotency isn't enforced.

* Webhook failures — out-of-order delivery, duplicate delivery during a gateway's own incident recovery, or a handler that isn't idempotent and double-processes the same event. A webhook handler needs to track event IDs and skip anything already processed, since gateways treat delivery as "at least once," not "exactly once." * Misrouted or misconfigured merchant IDs — a merchant ID not correctly mapped to its acquirer, or a routing rule silently sending traffic down the wrong path. * Token expiry — a payment token used too late in the flow fails even though nothing was wrong with the underlying card. Merchant-side fraud blocks (false declines). A meaningful share of "declines" never reach the issuer at all — the merchant's own fraud rules stopped them. This is diagnosed by checking whether the failure appears in the fraud tool's own logs versus an actual issuer response code, and it's worth treating as its own category precisely because it's invisible if you only ever look at issuer response codes. Recurring/subscription-specific causes. Stored-credential and subscription billing has a distinct failure profile: * A card that expired or was reissued since the last successful charge — the single most common cause, and one that clusters around specific expiry cycles rather than appearing randomly. * A transaction not flagged as recurring in the merchant's own billing system, which can cause an issuer to treat repeat charges as suspicious and decline out of caution.

* Retry cadence itself becoming a cause of failure: retrying too aggressively can get a card temporarily blocked, while retrying too passively (or only once) gives up on payments that would have succeeded on a second attempt timed differently. A retry schedule that spreads attempts across several days — rather than immediately repeating the same failed attempt — recovers meaningfully more revenue. Settlement and reconciliation breaks. These are a separate failure category from authorization failures and are easy to misdiagnose as "the payment failed" when the payment actually succeeded and a downstream record just doesn't match yet. Common patterns: * Timing gaps — different payment rails settle on different schedules, so a reconciliation system can flag a "mismatch" that's really just a rail that hasn't settled yet. * Duplicate postings — the same event recorded twice, often from the same webhook-idempotency issue described above. * Missing credits — a bank-side deposit arriving without a corresponding ledger entry, or vice versa. * FX/amount variance — a currency conversion or fee calculation that doesn't reconcile cleanly across the acquirer, the network, and the internal ledger.

The distinguishing diagnostic question for this category is when the discrepancy was found: at checkout (an authorization problem) or during reconciliation (a settlement/ledger problem) — and it's a genuine problem area, since a real-world analysis of complaint data found reconciliation issues concentrate specifically in platforms with the most complex multi-party payment routing. Building the tooling to do this repeatedly A one-off investigation is manageable manually; a recurring diagnostic capability needs infrastructure: * Centralize before you analyze. Pull data from every PSP and acquirer into one normalized pipeline — comparing providers is impossible if each one reports outcomes in its own format. * Layer dashboards by depth. An effective setup has an executive view (global approval rate, error rate, volume), an operational view (breakdowns by provider and region), and a diagnostic view (error codes, latency percentiles, retry behavior) — with fast drill-down from one to the next. * Alert on deviation, not just on absolute thresholds. Normal performance varies by region, payment method, issuer, and time of day, so a static "approval rate below X%" alert misses a real problem hiding in one segment while the aggregate looks fine. Anomaly-based monitoring that learns each segment's own baseline catches sudden shifts (a retry spike, a decline-reason change, an unusual regional traffic shift) that a flat threshold would miss entirely.

* Track economic anomalies alongside operational ones. A shift in interchange mix or a surge in scheme fees can quietly erode margin even while the top-line authorization rate looks completely healthy. A practical runbook 1. Pull the raw response — gateway log, decline code, HTTP status, or reconciliation exception. Don't start from the customer-facing error message. 2. Classify it — soft decline, hard decline, merchant-side block, technical error, authentication failure, or settlement break. 3. Segment it — by acquirer, issuer/BIN, region, and time, before drawing any conclusion from an aggregate number. 4. Check for clustering — does this fail only on one PSP, one country, one card type, or one time window? Isolated clusters point to a specific, fixable cause; broad, even distribution points to something more fundamental (pricing, product, or genuine fraud). 5. Match the fix to the category — retry soft declines on a sensible cadence, never retry hard declines, fix the integration for technical errors, adjust the rule for false declines, and treat settlement breaks as a data/timing investigation rather than a declined payment. 6. Close the loop — feed what you learned back into routing rules, retry logic, or fraud thresholds so the same failure pattern doesn't require a fresh investigation next month.

This guide synthesizes publicly available vendor documentation, developer guides, and industry commentary on payment failure diagnosis. Specific percentages and benchmarks cited by individual sources vary by methodology and business type; treat them as directional rather than universal. How to Diagnose Payment Failures "Payment failed" is a symptom, not a diagnosis. The same error message on a checkout page can mean an expired card, a misconfigured merchant ID, a webhook that never fired, or an issuer's fraud model having a bad day — and each of those needs a completely different fix. This guide walks through a systematic way to find out which one you're actually looking at. Start with the chain, not the symptom A payment touches several distinct systems, and a failure can originate at any link: Customer/client → Merchant application → Payment gateway/API → Acquirer → Card network → Issuing bank (and, separately, a settlement/reconciliation layer that runs after authorization and can fail independently of it).

The diagnostic discipline is one of elimination: start broad, then drill down through logs, network calls, and gateway data — letting the evidence (decline codes, exceptions, status codes) guide the investigation rather than guessing based on where the error happened to surface. A timeout on the customer's screen, for instance, doesn't tell you the transaction failed — it tells you you don't know what happened, since the charge may have gone through on the issuer's side even if your system never got the confirmation. Step 1: Get the actual data before forming a theory Read the gateway logs first. Review the logs from your payment gateway for the specific error code or message — "insufficient funds," "card declined," "expired card" — rather than working from the generic failure the customer saw. Capture full context per attempt, not just the response code. A bare decline code rarely tells the full story on its own; log the 3DS outcome, device type, BIN, attempt number, and timestamp alongside it, since root-cause analysis depends on that surrounding context.

Normalize response codes if you run more than one processor. Different gateways categorize the same underlying issuer response differently — one might label a transaction a generic gateway error while another calls it an issuer-side decline — and that classification mismatch is a common reason payment teams struggle to isolate the true root cause. Building one canonical mapping layer across providers is what makes cross-PSP analysis possible at all. Instrument the call itself. For technical/API failures, record latency, HTTP response code, decline reason (if any), and the idempotency key hash for every gateway call — this is what turns "it broke sometime this morning" into "it broke at 9:14am on Acquirer B with a 15% latency spike." Step 2: Classify the failure type before you act on it Not every failure is the same kind of failure, and treating them identically is the single most common diagnostic mistake. Category What's happening Diagnostic signal Right response Soft decline Issuer approved conceptually but flagged a temporary issue (insufficient funds, issuer system unavailable) Retrying later often succeeds Retry on a sensible schedule Hard decline Issuer permanently refused (invalid/expired/stolen card, closed account) Retrying the same card never succeeds Request a new payment method — don't retry Merchant-side fraud block Transaction never reached the issuer at all — your own rules stopped it Shows up in your fraud tool's logs, not the issuer's response

Audit the rule that fired; check for false-decline patterns Technical/integration error Gateway timeout, malformed request, webhook never delivered or processed twice HTTP-level errors, missing webhook events, duplicate ledger entries Fix the integration, not the customer's card Authentication failure 3DS challenge failed, OTP mismatch, signature validation failed Explicit 3DS/ACS status in the response Distinct from a card-level decline — check the authentication flow itself Settlement/reconciliation break Authorization succeeded, but a downstream ledger, bank, or payout record doesn't match Discovered in reconciliation, not at checkout Investigate as a data/timing issue, not a declined payment A useful gut-check: authorization rate (approvals as a share of requests the issuer actually saw) and approval rate (completed payments as a share of everything attempted, including your own blocked transactions) are different numbers — confusing them means you might be diagnosing your own fraud rules as if they were issuer behavior, or vice versa. Step 3: Segment before you conclude anything An aggregate failure rate hides almost everything useful. The same overall approval rate can coexist with a specific, fixable problem sitting one layer down — for example, an overall rate holding steady while "Do Not Honor" codes for one secondary processor in one country climb sharply, pointing to an upstream issuer or fraud-model issue invisible in the top-line number.

Before drawing a conclusion, break the data down by: * Acquirer / PSP — one processor can develop a problem while others stay healthy * Issuer and BIN range — a specific card portfolio can be behaving differently from the rest of your volume * Region / issuing country — cross-border and local patterns diverge substantially * Decline/response code — "Do Not Honor" behaves nothing like "Insufficient Funds" * Time — failures that cluster around specific days (payroll dates, card-expiry cycles) point to a customer-side cause; failures that spike suddenly point to a technical or configuration cause Modern payment-intelligence tooling automates this by continuously benchmarking current performance against historical baselines at the BIN/issuer/acquirer/route level and flagging statistically significant deviations — catching, for instance, a merchant ID that isn't correctly mapped to an acquirer, or transactions being silently routed down the wrong path, before the issue surfaces as a wave of support tickets. Common root causes, in more depth Card- and issuer-level causes. Insufficient funds, an expired or invalid card, a closed account, or the issuer blocking a transaction it perceives as unusual (foreign, high-value, or off-pattern for that cardholder) sit at this level. These are diagnosed from the decline code itself and are largely outside the merchant's direct control — though better transaction data (accurate AVS, CVV, and 3DS context) can influence the issuer's decision.

Technical and integration causes. These are diagnosed in your own logs, not the issuer's response, and include: * Gateway timeouts — the transaction takes too long and the gateway doesn't respond in time. * Duplicate requests — a user double-clicks "pay," and the system may block it as a duplicate or, worse, process it twice if idempotency isn't enforced. * Webhook failures — out-of-order delivery, duplicate delivery during a gateway's own incident recovery, or a handler that isn't idempotent and double-processes the same event. A webhook handler needs to track event IDs and skip anything already processed, since gateways treat delivery as "at least once," not "exactly once." * Misrouted or misconfigured merchant IDs — a merchant ID not correctly mapped to its acquirer, or a routing rule silently sending traffic down the wrong path. * Token expiry — a payment token used too late in the flow fails even though nothing was wrong with the underlying card. Merchant-side fraud blocks (false declines). A meaningful share of "declines" never reach the issuer at all — the merchant's own fraud rules stopped them. This is diagnosed by checking whether the failure appears in the fraud tool's own logs versus an actual issuer response code, and it's worth treating as its own category precisely because it's invisible if you only ever look at issuer response codes. Recurring/subscription-specific causes. Stored-credential and subscription billing has a distinct failure profile:

* A card that expired or was reissued since the last successful charge — the single most common cause, and one that clusters around specific expiry cycles rather than appearing randomly. * A transaction not flagged as recurring in the merchant's own billing system, which can cause an issuer to treat repeat charges as suspicious and decline out of caution. * Retry cadence itself becoming a cause of failure: retrying too aggressively can get a card temporarily blocked, while retrying too passively (or only once) gives up on payments that would have succeeded on a second attempt timed differently. A retry schedule that spreads attempts across several days — rather than immediately repeating the same failed attempt — recovers meaningfully more revenue. Settlement and reconciliation breaks. These are a separate failure category from authorization failures and are easy to misdiagnose as "the payment failed" when the payment actually succeeded and a downstream record just doesn't match yet. Common patterns: * Timing gaps — different payment rails settle on different schedules, so a reconciliation system can flag a "mismatch" that's really just a rail that hasn't settled yet. * Duplicate postings — the same event recorded twice, often from the same webhook-idempotency issue described above. * Missing credits — a bank-side deposit arriving without a corresponding ledger entry, or vice versa.

* FX/amount variance — a currency conversion or fee calculation that doesn't reconcile cleanly across the acquirer, the network, and the internal ledger. The distinguishing diagnostic question for this category is when the discrepancy was found: at checkout (an authorization problem) or during reconciliation (a settlement/ledger problem) — and it's a genuine problem area, since a real-world analysis of complaint data found reconciliation issues concentrate specifically in platforms with the most complex multi-party payment routing. Building the tooling to do this repeatedly A one-off investigation is manageable manually; a recurring diagnostic capability needs infrastructure: * Centralize before you analyze. Pull data from every PSP and acquirer into one normalized pipeline — comparing providers is impossible if each one reports outcomes in its own format. * Layer dashboards by depth. An effective setup has an executive view (global approval rate, error rate, volume), an operational view (breakdowns by provider and region), and a diagnostic view (error codes, latency percentiles, retry behavior) — with fast drill-down from one to the next.

* Alert on deviation, not just on absolute thresholds. Normal performance varies by region, payment method, issuer, and time of day, so a static "approval rate below X%" alert misses a real problem hiding in one segment while the aggregate looks fine. Anomaly-based monitoring that learns each segment's own baseline catches sudden shifts (a retry spike, a decline-reason change, an unusual regional traffic shift) that a flat threshold would miss entirely. * Track economic anomalies alongside operational ones. A shift in interchange mix or a surge in scheme fees can quietly erode margin even while the top-line authorization rate looks completely healthy. A practical runbook 1. Pull the raw response — gateway log, decline code, HTTP status, or reconciliation exception. Don't start from the customer-facing error message. 2. Classify it — soft decline, hard decline, merchant-side block, technical error, authentication failure, or settlement break. 3. Segment it — by acquirer, issuer/BIN, region, and time, before drawing any conclusion from an aggregate number. 4. Check for clustering — does this fail only on one PSP, one country, one card type, or one time window? Isolated clusters point to a specific, fixable cause; broad, even distribution points to something more fundamental (pricing, product, or genuine fraud).

5. Match the fix to the category — retry soft declines on a sensible cadence, never retry hard declines, fix the integration for technical errors, adjust the rule for false declines, and treat settlement breaks as a data/timing investigation rather than a declined payment. 6. Close the loop — feed what you learned back into routing rules, retry logic, or fraud thresholds so the same failure pattern doesn't require a fresh investigation next month.

This guide synthesizes publicly available vendor documentation, developer guides, and industry commentary on payment failure diagnosis. Specific percentages and benchmarks cited by individual sources vary by methodology and business type; treat them as directional rather than universal.