cardpointe logo
Developer Docs
Statuspage
Search Icon
Support
hamburger-menu

Overview 

 

To help merchants to better identify authorization declines and prevent incurring system integrity fees, Visa now provides additional Decline Category Codes, which instruct the merchant whether or not to retry a declined authorization attempt on a Visa card account.

 

This article provides detailed information on the CardPointe Gateway's implementation of these Decline Category Codes, and any changes you may need to make to your integrated application or business processes.

As of 10/22/2022, this feature is available for merchants processing on the following platforms:

  • First Data North
  • First Data Rapid Connect
  • Chase Paymentech Salem
  • Chase Paymentech Tampa
  • TSYS
  • Vantiv

Understanding Visa Decline Rules and Responses 

 

Visa has implemented rules and penalties to prevent merchants from reattempting declined transactions using incorrect data or accounts that will never be approved (for example a closed account).

Visa Excessive Reattempts Rule

As of April 2022, Visa assess fees on decline reattempts under its Excessive Reattempts Rule. An excessive reattempt is defined as one of either of the following:

  • A reattempt of a declined transaction that returned a Decline Category Code of 1 (never retry).
  • Each reattempt after the 15th in a 30 day period for a transaction that returned a Decline Category Code of 2 (wait and retry) or 3 (correct and retry).

For each transaction that meets one of these criteria, the merchant is subject to an excessive reattempt fee. This fee is assessed per  transaction, and is displayed on the merchant statement as "VI NEVER APPROVE REATTEMPT FEE."

Visa Decline Category Codes

To help merchants properly handle declined transactions and avoid excessive reattempt fees, Visa provides additional Decline Category Codes in the authorization response. These codes indicate whether or not the merchant should reattempt the transaction, and why.

The following table describes each code, its description, and some example cases:

Decline Category CodeDescriptionReattempt HandlingExamples
1

The issuer will never approve.

In this case, you should not reattempt the transaction using the same account information; it will never be approved by the issuer. 

Reattempting this transaction will incur a fee.

Instead, advise the cardholder to contact their issuer or provide an alternate payment method.

Some possible reasons for this code include:

  • The account has been closed.

  • The account has not been activated.

  • There is a stop payment order on this account.

2

The issuer cannot approve at this time.

In this case, you may wait and retry this transaction at a later time; the issuer may approve the transaction on a future attempt.

Note: You may reattempt this transaction a maximum of 15 times in a 30-day period before incurring excessive reattempt fees, unless you receive an updated declineCategory of 1, in which case you should no longer reattempt this transaction.

Some possible reasons for this code include:

  • The account has exceeded its daily transaction limit.

  • The cardholder exceeded the number of allowable PIN entry attempts.

  • The account currently has insufficient funds.

  • A system error occurred while authorizing the transaction.

3

The issuer cannot approve based on details provided.

In this case, you can check the account information for errors, correct any invalid data, and reattempt the transaction using the corrected data; the issuer might approve the transaction if all errors are corrected.

Note: You may reattempt this transaction a maximum of 15 times in a 30-day period before incurring excessive reattempt fees, unless you receive an updated declineCategory of 1, in which case you should no longer reattempt this transaction.

Some possible reasons for this code include:

  • The account number is invalid.

  • The card is expired.

  • The CVV entered is incorrect.

  • The PIN entered is incorrect.

Integrated Payment Application Changes 

 

The following topics describe important changes to the CardPointe Gateway API and related integrated payment applications to support the Visa Decline Category Codes.

CardPointe Gateway API

For declined Visa transactions, the CardPointe Gateway API now returns two new fields, declineCategory and declineCategoryText in the response from the following endpoints:

  • auth
  • refund
  • inquire
  • inquireByOrderId

The following table describes these new fields and potential values in detail:

FieldMax LengthTypeDescription
declineCategory1N

A numeric decline category code returned by the issuer.

One of the following values:

  • 1 - Issuer Will Never Approve.

    In this case, the merchant should never reattempt to authorize the transaction, and the cardholder must provide an alternate payment method. This code can be returned for accounts that are blocked, never existed, or are otherwise flagged as invalid by the issuer.

  • 2 - Issuer Cannot Approve at this Time.

    In this case, the merchant may reattempt the authorization at a later time. Reasons for this decline can include velocity controls, credit risk holds, or system errors.

  • 3 - Issuer Cannot Approve Based on Details Provided.

    In this case, the card has been declined due to incorrect data, such as the CVV, expiry, or PIN. The merchant may attempt the authorization, after obtaining the corrected data.

  • 4 - Generic Response returned for some processors.

declineCategoryText25AN

A text description to provide more information on the decline.

One of the following:

  • Do not retry - Returned for declineCategory 1.
  • Wait to retry - Returned for declineCategory 2.
  • Fix the request and retry - Returned for declineCategory 3.

For First Data Rapid Connect UAT transactions only, "declineCategory":"4" and "declineCategoryText":"" may be returned.

Visa Declined Transaction Response Example (First Data North)

 

    
       
{
    "amount": "10.00",
    "resptext": "Invalid card number",
    "declineCategoryText": "Fix the request and retry",
    "cardproc": "FNOR",
    "commcard": "N",
    "respcode": "14",
    "entrymode": "ECommerce",
    "merchid": "496160873888",
    "token": "9491785917235957",
    "respproc": "FNOR",
    "declineCategory": "3",
    "expiry": "1299",
    "retref": "243772239082",
    "respstat": "C",
    "account": "9491785917235957"
}

Expand the following table to review the relationship between some typical processor decline responses and their respective Visa Decline Category codes:
 

Testing Decline Category Codes 

The CardPointe Gateway UAT environment supports testing response scenarios using specific transaction amounts. Because the Visa decline category codes correspond to the authorization response, you can simulate various decline scenarios to retrieve the corresponding declineCategory and declineCategoryText values.

 

For example, to simulate the above scenario on the First Data North emulator, submit a test transaction with a Visa test card and "amount":"1014" to simulate a response with "respcode":"14" and "declineCategory":"2".

 

See Processing Host Response Codes for a list of possible response codes by processor.

 

See Testing With Amount-Driven Response Codes in the Testing Your Integration guide for additional information and examples.

CardPointe Integrated Terminal API

The following changes are in development and are subject to change.

A future update to the CardPointe Integrated Terminal API will include the declineCategory and declineCategoryText fields in the authorization response returned by the authCard and authManual endpoints.

You can use the CardPointe Gateway API inquire or inquireByOrderId request to retrieve the declineCategory and declineCategoryText fields for a transaction processed on the CardPointe Integrated Terminal.

CardPointe Application Changes 

An update to the CardPointe Mobile app to display these fields is planned for an upcoming release. 

The CardPointe web app now displays the following fields on the Transaction Detail page's Transaction History, to help merchants determine whether or not to reattempt the transaction with the given account information:

  • Decline Category Code - Displays the decline category code and a reason for the decline.
  • Decline Category Text - Displays instructions for the merchant.