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`
`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.

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`	`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
`blocked`	`do_not_try_again`	`workflow_blocked`	The payment was blocked by the workflow settings.
`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.

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.

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.

Network Code Mapping

PayNext automatically maps raw Visa and Mastercard response codes to standardized decline reasons:

Network Code	Description	Card Networks	Advice Code	Decline Reason
01	Refer to the card issuer	Mastercard	try_again_later	card_issuer_decline
03	Invalid merchant	Mastercard, Visa	do_not_try_again	generic_decline
04	Pickup card (no fraud) [Visa] / Capture card [Mastercard]	Mastercard, Visa	do_not_try_again	card_lost_or_stolen
05	Do not honor	Mastercard, Visa	try_again_later	do_not_honor
07	Pickup card, special conditions	Visa	do_not_try_again	card_lost_or_stolen
12	Invalid transaction	Mastercard, Visa	do_not_try_again	generic_decline
13	Invalid amount	Mastercard	do_not_try_again	generic_decline
14	Invalid card number	Mastercard, Visa	do_not_try_again	invalid_card_number
15	No such issuer	Mastercard, Visa	do_not_try_again	generic_decline
19	Re-enter transaction	Visa	try_again_later	issuer_unavailable
30	Format error	Mastercard	try_again_later	card_declined
41	(Pickup card) lost card	Mastercard, Visa	do_not_try_again	card_lost_or_stolen
43	(Pickup card) stolen card	Mastercard, Visa	do_not_try_again	card_lost_or_stolen
46	Closed Account	Visa	do_not_try_again	generic_decline
51	Insufficient funds / Not Sufficient Funds	Mastercard, Visa	try_again_later	insufficient_funds
54	Expired card / Expiration date missing	Mastercard, Visa	do_not_try_again	expired_card
57	Transaction not permitted to the issuer/cardholder	Mastercard, Visa	do_not_try_again	generic_decline
58	Transaction not permitted to the acquirer	Mastercard	do_not_try_again	generic_decline
59	Suspected fraud	Visa	do_not_try_again	suspected_fraud
61	Exceeds withdrawal amount limit(s) / Exceeds approval amount limit	Mastercard, Visa	try_again_later	withdrawal_limit_exceeded
62	Restricted card	Mastercard, Visa	do_not_try_again	generic_decline
63	Security violation	Mastercard	try_again_later	card_issuer_decline
65	Exceeds Withdrawal Frequency Limit	Mastercard, Visa	try_again_later	withdrawal_limit_exceeded
70	Contact card issuer	Mastercard	try_again_later	card_issuer_decline
76	Invalid/non-existent “To Account” specified	Mastercard	do_not_try_again	generic_decline
77	Invalid/non-existent “From Account” specified	Mastercard	do_not_try_again	generic_decline
78	Invalid/nonexistent account specified (general)	Mastercard	do_not_try_again	generic_decline
78	Blocked, first used	Visa	try_again_later	card_issuer_decline
79	Lifecycle	Mastercard	do_not_try_again	generic_decline
82	Policy	Mastercard	do_not_try_again	generic_decline
83	Fraud / Security	Mastercard	do_not_try_again	suspected_fraud
84	Invalid Authorization Lifecycle	Mastercard	do_not_try_again	generic_decline
88	Cryptographic failure	Mastercard	do_not_try_again	generic_decline
91	Issuer unavailable or switch inoperative	Mastercard, Visa	try_again_later	issuer_unavailable
92	Unable to route transaction	Mastercard	try_again_later	card_declined
93	The transaction cannot be completed; violation of the law	Visa	do_not_try_again	generic_decline
96	System malfunction	Mastercard, Visa	try_again_later	issuer_unavailable
R0	Stop Payment Order	Visa	do_not_try_again	generic_decline
R1	Revocation of Authorization Order	Visa	do_not_try_again	generic_decline
R3	Revocation of all authorization orders	Visa	do_not_try_again	generic_decline
N7	Decline for CVV2 Failure	Visa	do_not_try_again	incorrect_cvc
1A	Additional Customer Authentication Required (Europe only)	Visa	try_again_later	authentication_required

Introduction

Use Cases

Platform

Payments

Fraud Prevention

Advanced Features

Developers

Payload Example

Response Fields

Available Codes

Incomplete Payments

Response Example

Network Code Mapping

​Payload Example

​Response Fields

​Available Codes

​Incomplete Payments

​Response Example

​Network Code Mapping

Payload Example

Response Fields

Available Codes

Incomplete Payments

Response Example

Network Code Mapping