> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paynext.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Decline Codes
> Unified status mapping across all processors—understand why a payment failed and whether to retry.
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
```json theme={"system"}
{
"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](#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](/guides/platform/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](/guides/use-cases/recover-subscriptions) for subscription renewals or the [SDK checkout](/sdk-reference/use-cases/charge-saved-payment-methods) 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
```json theme={"system"}
{
"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](/guides/payments/3d-secure) for details.
If 3DS credentials are misconfigured, you receive a `failed` payment. See [Configure External 3DS Per Processor](/guides/payments/3d-secure#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 |