Follow

Decline Handling

Unless you are already familiar with declines in PayJunction, it is highly recommended to read this section.

Gracefully handling declines goes a long way towards minimizing friction and frustrations for merchants and cardholders alike. Therefore it is important we talk about the different types of declines in PayJunction, along with a few specific declines that integrators should understand before starting.

There are, broadly speaking, three types of declines:

  • Issuer Declines
  • Gateway Declines Before Issuer Authorization
  • Gateway Declines After Issuer Authorization

TIP: As a general rule of thumb, decline codes and messages should only be shown to the merchant and not the cardholder. Especially for eCommerce platforms, showing this information can make your service a tempting target for testing stolen card numbers or otherwise direct a malicious user on how to push through a fraudulent transaction.

A full list of decline codes returned by the API can be found here.

Issuer Declines

When the card issuing bank declines a transaction, PayJunction does not receive an authorization code, funds are not reserved in the cardholder's account and the merchant is not funded. This is the most common type of decline and will always include a numeric value for the code parameter in the response object of the transaction details:

{
     'status': 'DECLINED',
     'response': {
          'message': 'Declined (do not honor)',
           'code': '05',
          'approved': False,
          'processor': {
               'cvv': {
                    'status': 'NOT_REQUESTED'
               },
               'authorized': False,
               'avs': {
                    'status':
                    'NOT_REQUESTED'
               }
          }
     },
     ...
}

With this type of decline no funds are reserved by the issuing bank.

Do Not Honor (05)

This decline code and message are worth discussing as it often confuses merchants. Do Not Honor (05) is the generic decline message that an issuer returns when a more specific decline message (e.g. Insufficient Funds (51), Exceeds Activity Limit (65)) is unavailable or if the issuer does not want to specify the exact reason for the decline, such as when fraud is suspected. Some of the possible scenarios that can trigger this decline are:

  • Sending the wrong expiration date for the card on a keyed transaction.
  • Keying in a large transaction on a merchant account that is set to Retail (i.e. Keying in transaction details on an account that is setup to accept swiped transactions).
  • Keying in a large transaction without processing the card security code (CVV).
  • Processing duplicate transactions on a card.
  • Processing large transactions on the same card in close proximity to each other, such as on the same day.

When this type of decline is received, the cardholder should call the toll-free number on the back of the card to speak with a bank representative to ask why the charge was declined as "Do Not Honor". A common mistake is to ask if the funds are available or if there is enough money in the account; this is not a decline indicating the funds are unavailable (i.e. Insufficent Funds (51)).

For a full list of these types of declines see the DECLINE CODES section of our Response Code Definitions article on the PayJunction Knowledge Base.

Gateway Declines Before Issuer Authorization

These types of declines are always returned as two-character non-numeric values (e.g. Duplicate Transaction (DT), Exceeded Limit Per Transaction (LT)). With these declines the transaction is blocked by PayJunction and are never sent to the issuer for authorization.

Except for the codes listed in Gateway Declines After Issuer Authorization section below, these decline codes indicate that the issuer never received a request to approve the transaction and no funds are being reserved.

As the transaction never makes it to the issuer, the merchant should contact the PayJunction support department for assistance if needed.

For a full list of these types of declines see the PAYJUNCTION SPECIFIC DECLINE CODES section of our Response Code Definitions article on the PayJunction Knowledge Base.

Duplicate Transaction (DT)

PayJunction's gateway service assumes that two transactions, for the same amount, on the same card, within 10 minutes of each other, is an error. This behavior can be overridden easily by sending a different invoice number with the transaction details using the invoiceNumber parameter. One of the most common mistakes integrators make when implementing the API is to randomly generate a new invoice number every time the function is called to process a transaction. While it is a simple solution to allow duplicate transactions to be ran on the same card, using this strategy removes the protection offered by this decline.

In a world of interactive, event-driven UIs, it is easy to allow an event to bubble up and trigger a function unintentionally or to accidentally allow multiple form submissions on user input (e.g. not disabling the submit button after the first click in an HTML form). If you are generating a random invoice number every time the function is called, PayJunction cannot stop this error from impacting the cardholder and charging them multiple times.

Exceeded Limit Per Transaction (LT) & Exceeded Limit Per Month (LM)

Unlike most merchant acquirers, PayJunction enforces transaction limits at the time of authorization. These declines should not be confused with the Exceeds Activity Limit (65) decline, which indicates a limit on the payment card account attempting to be charged. In the case of these declines the merchant should contact the Risk department at PayJunction for assistance and any decline message should explicitly state this for the merchant. It is PayJunction's firm belief that it is better to work with a merchant to make sure they are protecting themselves from chargeback liability and risk than to hold funds or watch a merchant lose a large chargeback case that could have been won or prevented entirely.

Gateway Declines After Issuer Authorization

TIP: These types of declines will only occur on keyed-in transactions, or in the case that a chip card is removed from a Smart Terminal before it has fully processed the transaction with the issuer.

The following decline messages are related to fraud prevention. As security continues to increase for retail transactions with the advent of EMV, more and more payment card fraud is being directed to keyed in transactions, particularly eCommerce. By default, PayJunction accounts require verification of the three or four digit security code printed on a card as well as the street address number and zip code on file at the issuing bank. However, PayJunction does not validate this information until after it has sent the transaction to the issuer for approval. Once the issuer approves the transaction it then provides PayJunction with the information about what did or did not match along with the approval code.

As discussed above, once a transaction has been authorized, the funds are immediately reserved in the account. Depending on the card type and issuer, these reservations can take up to 3 business days or longer to drop off the cardholder’s balance and statement. Until that time has passed, the cardholder cannot use those funds to make other payments.

Address Verification Security (AVS) Declines (AX, AZ, AA, AI, AY, AW, AN)

These decline messages are dependent on the address verification method used when processing the transaction, as well as on the card issuer and whether or not they support AVS. The most important thing to remember is that other than the exception listed below, receiving this decline message means that the card issuing bank approved the transaction and is reserving the funds.

When a card issuing bank receives a keyed-in transaction, it tries to verify the zip code provided as well as the street address number. Each issuer decides how they are going to parse the street address number from the full street address sent to them and some are better than others. Here are a few common scenarios that can lead to a false-negative response from the bank when matching the street address:

  • PO Box addresses
  • Addresses with numbers other than the street address number
  • e.g. 123 5th St
  • e.g. 123 Main St Apt 5

AVS declines can be overridden by the merchant in the PayJunction Virtual Terminal web portal but not currently through the API. For service providers with merchants in higher fraud risk categories, who want to verify address info and give their merchants the option to accept or decline a transaction without a full address match, it is recommended to set the avs parameter to BYPASS when sending keyed transactions to PayJunction for processing. The results of the street address and zip code verification will be included in the response object of the transaction details:

...
     "response": {
          "approved": true, 
          "code": "00",
          "message": "Approved",
          "processor": {
               "authorized": true,
               "approvalCode": "PJ20AP", 
               "avs": {
                    "status": "REQUESTED",
                    "requested": "BYPASS",
                     "match": {
                          "ZIP": true, 
                          "ADDRESS": true
                     }
               },
               "cvv": {
                    "status": "NOT_REQUESTED"
               }
          }
     },
...


If the merchant chooses not to trust the cardholder, the transaction can then be voided through the API. This is technically the action PayJunction's system performs with AVS declines that are not overridden.

Card Verification Value Declines (CV & 97)

There are two types of declines based on the card security code verification. If the decline code is 97 then the card issuer is blocking the transaction and there is no authorization on the card holder's account. Some issuers however will approve the transaction regardless of a matching security code, in which case PayJunction will decline the charge with the CV code if CVV is turned on. In the case of a CV decline the funds are being held by the issuing bank.