Decline Codes

Every processor returns decline codes in different formats. PayNext normalizes these into a unified system so you get consistent analytics, predictable retry logic, and clear decline reasons regardless of which processor handled the payment. When a payment doesn’t succeed, PayNext returns a status and status_reason:

Status	Meaning
`FAILED`	Technical or system error (timeout, malformed request)
`DECLINED`	Issuer or processor rejected the payment
`BLOCKED`	Payment blocked by workflow settings
`INCOMPLETE`	Customer didn’t complete authentication

Payload Example

{
  "status": "declined",
  "status_reason": {
    "advice_code": "try_again_later",
    "decline_code": "insufficient_funds",
    "message": "Card has insufficient funds"
  }
}

Response Fields

Field	Description	Example values
`status`	Payment outcome	`failed`, `declined`, `blocked`, `incomplete`
`status_reason.advice_code`	Retry guidance	`try_again_later`, `do_not_try_again`, `retry_via_another_processor`
`status_reason.decline_code`	Standardized decline code	`issuer_unavailable`, `insufficient_funds`, `expired_card`
`status_reason.message`	Human-readable description from processor	Not enough funds available.

Available Codes

Standard declines are listed below. Authentication-specific codes are covered in Incomplete Payments. The same decline_code can arrive with more than one status or advice_code, depending on the processor and on what it returned, so always read the advice_code of the payment itself.

status	advice_code	decline_code	message
`declined`	`try_again_later`	`insufficient_funds`	Not enough funds available.
`declined`	`try_again_later`	`do_not_honor`	Issuer declined the transaction.
`declined`	`try_again_later`	`withdrawal_limit_exceeded`	Transaction exceeds the payment method limit.
`declined`	`try_again_later`	`issuer_unavailable`	Issuer temporarily unavailable.
`declined`	`try_again_later`	`card_declined`	Card declined by the issuer.
`declined`	`try_again_later`	`card_issuer_decline`	The issuer refused the card: it is restricted, not yet activated, or does not support this type of purchase.
`declined`	`try_again_later`	`authentication_required`	The issuer or processor requires 3D Secure for this payment. Retry with customer authentication.
`declined`	`try_again_later`	`stop_payment_order`	The cardholder asked the issuer to stop this payment.
`declined`	`try_again_later`	`generic_decline`	Declined without a more specific reason.
`declined`	`do_not_try_again`	`card_lost_or_stolen`	The card has been reported lost or stolen.
`declined`	`do_not_try_again`	`invalid_card_number`	The card number is invalid.
`declined`	`do_not_try_again`	`expired_card`	The payment method has expired.
`declined`	`do_not_try_again`	`suspected_fraud`	The issuer flagged this payment as suspected fraud.
`declined`	`do_not_try_again`	`incorrect_cvc`	CVC verification failed
`declined`	`do_not_try_again`	`card_closed`	The account behind the card is closed. No replacement card is coming.
`declined`	`do_not_try_again`	`revocation_of_authorization`	The cardholder withdrew their authorization for recurring payments to this merchant (for example, Visa `R1` or `R3`).
`declined`	`do_not_try_again`	`stop_payment_order`	The cardholder asked the issuer to stop this payment (for example, Visa `R0`).
`declined`	`do_not_try_again`	`card_issuer_decline`	The issuer refused the card and will not approve it on a retry.
`declined`	`do_not_try_again`	`authentication_required`	3D Secure is required for this payment, and a retry without authentication will not succeed.
`declined`	`do_not_try_again`	`invalid_request`	The processor rejected the transaction as not allowed or invalid for this merchant account.
`declined`	`do_not_try_again`	`generic_decline`	Declined without a more specific reason, and a retry is not expected to succeed.
`declined`	`retry_via_another_processor`	`authentication_required`	The processor requires 3D Secure for this payment. Another processor may accept it.
`declined`	`retry_via_another_processor`	`card_issuer_decline`	Declined on this processor’s route. Another processor may accept it.
`blocked`	`do_not_try_again`	`workflow_blocked`	The payment was blocked by the workflow settings.
`blocked`	`retry_via_another_processor`	`processor_blocked`	The processor refused to handle the payment. Another processor may accept it.
`incomplete`	`do_not_try_again`	`payment_method_disabled`	The payment was not attempted: the customer revoked the mandate for this payment method.
`incomplete`	`do_not_try_again`	`payment_method_disabled`	No chargeable credential: network token not active and card not usable.
`failed`	`do_not_try_again`	`invalid_request`	The processor rejected the request before any issuer decision, for example because of a merchant account or 3D Secure credential misconfiguration, or an invalid token or network transaction ID.
`failed`	`try_again_later`	`invalid_request`	The processor rejected the request, for example as a duplicate or as a second scheduled payment in the same billing cycle.
`failed`	`do_not_try_again`	`card_issuer_decline`	The processor could not use the saved mandate for this payment method.
`failed`	`try_again_later`	`generic_decline`	The processor rejected the request without a more specific reason.
`failed`	`do_not_try_again`	`generic_decline`	The processor rejected the request, and a retry with the same details is not expected to succeed.
`cancelled`	`do_not_try_again`	`generic_decline`	The authorization was voided or the payer account could not be used.

Subscription Impact: When a recurring (MIT) payment is blocked via workflow, the associated subscription is immediately cancelled—no retries are attempted. PayNext sends a subscription_v2.cancelled webhook and stops scheduling future payments. Review your workflow conditions carefully to avoid unintended cancellations.

payment_method_disabled means PayNext never contacted the processor. The saved payment method can’t be charged—either the customer revoked its mandate, or neither the card nor its network token is usable. The message field tells the two apart. There is no processor decline behind it, so retrying the same payment method always produces the same result. Collect a new payment method instead. See Payment Methods.

retry_via_another_processor means the decline came from the processor or its acquirer, not from the card, so the same card can succeed through a different processor. It can come with different decline codes, such as processor_blocked. To act on it automatically, route the payment to a second processor in a workflow. See Automatic Failover.

For do_not_try_again declines like expired_card or invalid_card_number, the customer must provide a new payment method. Use Recover Subscriptions for subscription renewals or the SDK checkout for one-time payments.

Incomplete Payments

Payments that require customer authentication (Cash App, Venmo, cards with 3DS) can end as incomplete if the customer doesn’t finish the flow.

Decline Code	When It Occurs
`payment_attempt_authentication_failed`	Customer failed authentication (wrong OTP, declined in wallet app, failed biometric, issuer rejection)
`payment_attempt_authentication_cancelled`	Customer abandoned the flow (closed window, timed out, did not complete authentication)

Response Example

{
  "status": "incomplete",
  "status_reason": {
    "advice_code": "",
    "decline_code": "payment_attempt_authentication_cancelled",
    "message": "The provided payment method has not completed authentication."
  }
}

For card payments with 3DS, additional context is available in the three_d_secure object. See 3D Secure for details.

If 3DS credentials are misconfigured, you receive a failed payment. See Configure External 3DS Per Processor to update the configuration.

Card network response codes

When a Visa or Mastercard issuer declines a card payment, the processor passes along the issuer’s two-character response code. PayNext reads that code and returns it to you as a decline_code and an advice_code.

How the networks classify declines

Both networks tell merchants which declines they may retry, and how often.

Visa puts every decline response code into one of four categories. Category 1 means the issuer will never approve the card, so you must not retry it. Categories 2 (cannot approve right now), 3 (payment details need correcting) and 4 (all other codes) allow up to 20 retries in 30 days. Source: Visa Core Rules and Visa Product and Service Rules, April 2026 edition, section 7.3.6.3.
Mastercard names six codes (04, 14, 15, 41, 43, 54) that end a card-not-present payment for good: you must not retry it with the same card number and expiry date. For merchant-initiated payments, the issuer can also send a Merchant Advice Code: 01 means you should get updated card details first, 02 means you should wait at least 24 hours, and 03 or 21 mean you should stop. Source: Mastercard Transaction Processing Rules, June 2026 edition.

The tables below group codes by the Visa category they belong to, followed by the Mastercard codes that have no Visa counterpart. Some codes mean different things on each network. For 65 and 78, PayNext checks the card brand and maps each network’s meaning separately.

The network rules set the most you can retry. PayNext’s advice_code can be stricter. For example, Visa puts 03, 59, 62 and 93 in Category 2, but PayNext returns do_not_try_again for them.

Issuer will not approve the card (Visa Category 1)

Do not retry these payments with the same card. Ask the customer for a different payment method.

Code	Network	What the issuer is saying	`decline_code`	`advice_code`
`04`	Visa, Mastercard	Keep or capture the card	`card_lost_or_stolen`	`do_not_try_again`
`07`	Visa	Keep the card: fraud on the account	`card_lost_or_stolen`	`do_not_try_again`
`12`	Visa, Mastercard	The transaction is not valid for this card	`generic_decline`	`do_not_try_again`
`14`	Visa, Mastercard	No account matches this card number	`invalid_card_number`	`do_not_try_again`
`15`	Visa, Mastercard	The card number belongs to no known issuer	`generic_decline`	`do_not_try_again`
`41`	Visa, Mastercard	The card was reported lost	`card_lost_or_stolen`	`do_not_try_again`
`43`	Visa, Mastercard	The card was reported stolen	`card_lost_or_stolen`	`do_not_try_again`
`46`	Visa	The account is closed	`generic_decline`	`do_not_try_again`
`57`	Visa, Mastercard	The cardholder is not allowed to make this transaction	`generic_decline`	`do_not_try_again`
`R0`	Visa	The cardholder asked the issuer to stop this payment	`stop_payment_order`	`do_not_try_again`
`R1`	Visa	The cardholder withdrew the authorization for this merchant	`revocation_of_authorization`	`do_not_try_again`
`R3`	Visa	The cardholder withdrew all recurring authorizations	`revocation_of_authorization`	`do_not_try_again`

Issuer cannot approve right now (Visa Category 2)

Visa allows a retry later, for example after the customer adds funds or the issuer’s systems recover.

Code	Network	What the issuer is saying	`decline_code`	`advice_code`
`03`	Visa, Mastercard	The issuer does not recognize the merchant	`generic_decline`	`do_not_try_again`
`19`	Visa	Send the transaction again	`issuer_unavailable`	`try_again_later`
`51`	Visa, Mastercard	The account lacks the funds or credit	`insufficient_funds`	`try_again_later`
`59`	Visa	The issuer suspects fraud	`suspected_fraud`	`do_not_try_again`
`61`	Visa, Mastercard	The amount is over the card’s limit	`withdrawal_limit_exceeded`	`try_again_later`
`62`	Visa, Mastercard	The card is restricted, for example in this country	`generic_decline`	`do_not_try_again`
`65`	Visa	An activity limit was reached; PayNext treats it as a request to authenticate the cardholder	`authentication_required`	`try_again_later`
`65`	Mastercard	The card’s transaction count limit was reached	`withdrawal_limit_exceeded`	`try_again_later`
`78`	Visa	The account is temporarily blocked, for example before first use	`card_issuer_decline`	`try_again_later`
`83`	Visa, Mastercard	Declined by the network for fraud or security reasons	`suspected_fraud`	`do_not_try_again`
`91`	Visa, Mastercard	The issuer or its switch is not responding	`issuer_unavailable`	`try_again_later`
`93`	Visa	Completing the transaction would break the law	`generic_decline`	`do_not_try_again`
`96`	Visa, Mastercard	The issuer’s system failed	`issuer_unavailable`	`try_again_later`

Payment details need correcting (Visa Category 3)

A retry with the same details fails again. Collect corrected or new card details first. Mastercard also lists 54 among the codes you must not retry with the same card number and expiry date.

Code	Network	What the issuer is saying	`decline_code`	`advice_code`
`54`	Visa, Mastercard	The card has expired, or no expiry date was sent	`expired_card`	`do_not_try_again`
`N7`	Visa	The CVV2 check failed	`incorrect_cvc`	`do_not_try_again`

Generic and Mastercard-specific codes (Visa Category 4)

Visa treats any code outside the first three categories as generic. Most codes here are sent only by Mastercard.

Code	Network	What the issuer is saying	`decline_code`	`advice_code`
`01`	Mastercard	Contact the issuer about this payment	`card_issuer_decline`	`try_again_later`
`05`	Visa, Mastercard	Declined without a specific reason	`do_not_honor`	`try_again_later`
`13`	Mastercard	The amount is not valid	`generic_decline`	`do_not_try_again`
`30`	Mastercard	The authorization message was malformed	`card_declined`	`try_again_later`
`58`	Mastercard	The acquirer is not allowed to process this transaction	`generic_decline`	`do_not_try_again`
`63`	Mastercard	A security rule was violated	`card_issuer_decline`	`try_again_later`
`70`	Mastercard	The cardholder should contact the issuer	`card_issuer_decline`	`try_again_later`
`76`	Mastercard	The destination account is not valid	`generic_decline`	`do_not_try_again`
`77`	Mastercard	The source account is not valid	`generic_decline`	`do_not_try_again`
`78`	Mastercard	The account is not valid or does not exist	`generic_decline`	`do_not_try_again`
`79`	Mastercard	Declined for a card lifecycle reason	`generic_decline`	`do_not_try_again`
`82`	Mastercard, Visa	Mastercard: declined by issuer policy. Visa: the card security check failed	`generic_decline`	`do_not_try_again`
`84`	Mastercard	The authorization lifecycle is not valid	`generic_decline`	`do_not_try_again`
`88`	Mastercard	A cryptographic check failed	`generic_decline`	`do_not_try_again`
`92`	Mastercard	The transaction could not be routed	`card_declined`	`try_again_later`

Introduction

Use Cases

Platform

Payments

Fraud Prevention

Advanced Features

Developers

Payload Example

Response Fields

Available Codes

Incomplete Payments

Response Example

Card network response codes

How the networks classify declines

​Payload Example

​Response Fields

​Available Codes

​Incomplete Payments

​Response Example

​Card network response codes

​How the networks classify declines

Payload Example

Response Fields

Available Codes

Incomplete Payments

Response Example

Card network response codes

How the networks classify declines