PayFacto API - v2.0 - Decline Codes

Full lookup table of decline codes returned in result.declineCode when a charge is declined. Each code maps to a CARD_ERROR response with HTTP 402. Use this reference to surface accurate messaging to customers and decide whether to retry or request an alternate payment method.

Contents

❌️Overview 📋Where Decline Codes Appear 💰Funds & Account Issues 💳Card Data Issues 🔒Security & Fraud ⚠️Processing & Network Issues 🔄Handling Recommendations

❌️

Overview

When a card issuer declines a transaction, the API returns HTTP 402 with a CARD_ERROR error type. The specific reason for the decline is found in result.declineCode. These codes are normalized by PayFacto from the raw issuer and network response codes, so the same decline code value is returned regardless of card brand or acquirer.

ℹ️

Decline codes are descriptive only — they do not indicate a problem with your integration. A DO_NOT_HONOR or INSUFFICIENT_FUNDS response means the request reached the issuer successfully and was processed correctly; the issuer simply declined it.

📋

Where Decline Codes Appear

JSON — Declined charge (HTTP 402)

{
  "type":    "CARD_ERROR",
  "message": "The card was declined by the issuer.",
  "code":    "card_declined",
  "result": {
    "declineCode":           "INSUFFICIENT_FUNDS",
    "isoResponseCode":       "051",
    "issuerMessage":         "INSUFFICIENT FUNDS",
    "processorResponseCode": "05"
  }
}

declineCode is the normalized value to branch your logic on. isoResponseCode and processorResponseCode are the raw upstream codes, useful for logging and reconciliation but not recommended for application logic since their exact values can vary by processor.

💰

Funds & Account Issues

Decline Code	Description	Recommended Action
INSUFFICIENT_FUNDS	The card account balance is too low to cover the transaction amount.	Ask the customer to use another card or reduce the amount.
DO_NOT_HONOR	Generic decline. The issuer did not provide a more specific reason — often used as a catch-all for risk-based declines.	Ask the customer to use another card or contact their bank.
ACCOUNT_CLOSED	The card account has been closed by the cardholder or the issuer.	Ask the customer to use another card.
EXCEEDS_WITHDRAWAL_LIMIT	The transaction exceeds the card's daily or per-transaction limit.	Ask the customer to try a smaller amount or another card.
TRANSACTION_NOT_ALLOWED	The card type or merchant category is not permitted for this transaction (e.g. cash-only card used online).	Ask the customer to use a different card.

💳

Card Data Issues

Decline Code	Description	Recommended Action
EXPIRED_CARD	The card expiry date submitted has already passed.	Ask the customer for a new card.
INVALID_CARD_NUMBER	The card number failed Luhn validation or is not a recognized format.	Verify the card number was entered correctly and retry.
INVALID_CVV	The CVV submitted does not match the issuer's record.	Ask the customer to re-enter their CVV.
INVALID_EXPIRY_DATE	The expiry date format is invalid or does not match the issuer's record.	Ask the customer to re-enter the expiry date.
CARD_NOT_SUPPORTED	The card type or BIN range is not supported by this processing configuration.	Ask the customer to use a different card.

🔒

Security & Fraud

Decline Code	Description	Recommended Action
LOST_OR_STOLEN_CARD	The card has been reported lost or stolen by the cardholder.	Do not retry. Do not provide details to the customer beyond a generic decline message. Contact PayFacto Support if suspicious activity is suspected.
SUSPECTED_FRAUD	The issuer or fraud system flagged the transaction as high-risk.	Do not retry automatically. Consider manual review if your fraud rules allow it.
CARD_NOT_ENROLLED	The card is not enrolled for 3D Secure authentication.	Proceed without 3DS or decline per your fraud policy, depending on your risk tolerance.
AUTHENTICATION_FAILED	3D Secure authentication was attempted but failed or was abandoned by the cardholder.	Ask the customer to retry the authentication step or use another card.

⚠️

Processing & Network Issues

Decline Code	Description	Recommended Action
DUPLICATE_TRANSACTION	The network or issuer detected a duplicate transaction (same card, amount, and merchant within a short window).	Check if the original transaction was already processed successfully before resubmitting.
ISSUER_UNAVAILABLE	The card issuer's systems could not be reached to authorize the transaction.	Retry once after a short delay. If it persists, ask the customer to try another card.
INVALID_MERCHANT	The merchant account configuration is not valid for this transaction type.	Contact PayFacto Support — this typically indicates a setup issue rather than a card issue.
RESTRICTED_CARD	The card has restrictions that prevent this type of transaction (e.g. domestic-only card used internationally).	Ask the customer to use a different card.

🔄

Handling Recommendations

General guidance for building decline handling into your checkout flow:

Never expose raw codes to customers

Map each declineCode to a friendly, actionable message in your UI. Customers should never see raw values like DO_NOT_HONOR or isoResponseCode.

Distinguish retryable from non-retryable

Codes like ISSUER_UNAVAILABLE may succeed on retry after a delay. Codes like LOST_OR_STOLEN_CARD or INVALID_CVV will not — prompt for a different card or corrected input instead.

Log isoResponseCode and processorResponseCode

Keep the raw codes in your logs for reconciliation and support escalation, even though your application logic should branch on declineCode.

Apply rate limiting on retries

Limit automatic or customer-prompted retries (e.g. 3 attempts) to avoid triggering velocity-based fraud rules at the issuer or network level