A decline code is generated for all transactions, successful or not. It is crucial for understanding the transaction outcome, assisting merchants and customers. It helps pinpoint the cause of a failed transaction, allowing the merchant to help the customer resolve the issue.

For unsuccessful orders, the decline code is tied to both the transaction and order level, offering clear insight into the reason for the failure.

Here is an example of a decline code in a JSON API response from Solidgate for an unsuccessful transaction:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

{
  "status": "declined",
  "errors": [
    {
      "code": "2.08",
      "message": "Invalid card number"
    }
  ],
  "transaction": {
    "id": "trn_123456789",
    "status": "DECLINED",
    "amount": 100.00,
    "currency": "USD",
    "order_id": "ord_987654321",
    "decline_code": "2.08"
  }
}

In this example, the decline code “2.08” represents an invalid card number. The associated decline message is also included in the response, providing merchants with the necessary information to address the issue with the customer.

Recommendations for handling this decline code would be to kindly ask the user to re-enter a valid card number or try using a different card for the transaction.

0.01 General decline

The general group of declines. The card issuing bank did not complete the transaction successfully.

Kindly ask the user to try to pay a couple more times. The chances are high that the next attempt will be successful.

0.02 Order expired

The user could not finalize the payment during the given timeframe, which resulted in order expiration.

Kindly suggest to the user to try again with the same card.

0.03 Illegal operation (violation of law)

In some cases, the card issuer can block a transaction for law violation reasons. It can be due to a cardholder or due to a sanctioned country.

Kindly suggest to the user to use another card.

1.01 Authentication failed

Cardholder authentication was not successful.

Kindly ask the user to try to pay a couple more times. The chances are high that the next attempt will be successful.

2.01 Invalid Data/Order not found

“Invalid data” code message is used for validation errors, with the reason for the validation triggering specified in the body (object error) of the response.

The problem typically indicates that the information provided in the transaction request is incorrect or incomplete. This can happen for a variety of reasons, such as an incorrect card number or expiration date, an invalid security code, or an incorrect billing address.

Invalid data can also indicate that a required field is missing, such as the cardholder’s name or the transaction amount.

Also, the code message “Order not found” is used as a decline on orders in case of API response to request on non-existent order.

Kindly contact Solidgate Support for assistance.

2.02 Invalid Amount

There is a limit on the amount of the order on the acquiring side.

Kindly contact Solidgate Support.

2.03 Invalid Currency

The currency here is not supported.

Kindly contact Solidgate Support. More likely, we will be able to suggest a solution for you.

2.05 Order not found

This error can occur for a variety of reasons, such as when an order is cancelled or has already been processed, or when the order number provided is incorrect.

To troubleshoot this error, it’s recommended to check the order status and the order number, to make sure the order is not cancelled or already processed. Also, it’s important to double-check the order number to make sure it is accurate, as a typo or transposition error could also result in this error. Additionally, it might be useful to check if the order number is not expired.

If the error persists, kindly contact Solidgate Support for assistance.

2.06 Invalid CVV2 code

Invalid CVV2 code.

The CVV code is the three-digit code on the back of a MasterCard or Visa, or the four-digit code on the front of an American Express.

If it is the first occasion - kindly ask the user to try one more time.

If CVV code error is recurring for the same user - potential card fraud. Act accordingly to your policies.

2.07 Request Is empty

An error with a “payment request is empty” typically means that the information being sent to initiate the payment is incomplete or missing. This can happen for a number of reasons, such as a problem with the application or website that is sending the request, an issue with the customer’s payment method, or a technical error on the payment processor’s end.

If this error occurs, it is important to check that all required fields for the payment request are properly filled out, and that the customer’s payment method is valid and up-to-date. Additionally, checking for any issues on the application or website that is sending the payment request, and ensuring that the payment processor is functioning properly.It is also possible that the customer’s session has expired or, they have navigated away from the payment page before submitting the payment, so it is important to check that the customer is still on the payment page and their session is still active.

2.08 Invalid card number

The user entered an incorrect card number.

Kindly ask the user to enter a valid card number.

2.09 Invalid expiration date

Card is expired.

Kindly ask the user to check the expiration date and, if expired - use another card.

If the user insists that the card expiration date is yet to be, kindly contact Solidgate support.

2.10 Invalid 3DS flow on the merchant side

3DS URL was not displayed to the cardholder during 3D Secure authentication attempts.

Kindly ask a user to recall the step-by-step payment flow and forward information received to Solidgate Support.

2.11 Invalid 3DS flow on the bank side

The user went through a payment flow, but the bank did not initiate 3DS authorization.

Kindly ask the user to try one more time or suggest to the user to use another card.

2.12 Invalid 3DS flow

User hesitated with 3D Secure authentication.

Kindly ask the user to try one more time or suggest to the user to use another card.

2.13 Invalid IP

Incorrect IP address.

The merchant must pass a valid IP address in the request.

2.14 Subscription Error

This error indicates that the user already has a subscription to the product_id .

Please note, the user as customer_account_id can have only one active subscription within the same subscription product_id .

Check the customer_account_id of the user who is trying to make a purchase and their active subscriptions.

Make sure that you are using the correct product_id within your request, as it is an obligatory parameter for the subscription flow that specifies the subscription product.

2.15 SCA require 3D authentication

The order was tried to be processed without 3D verification, in cases of the EU transactions, which require 3D authentication.

Please contact Solidgate Support.

2.16 Subscription is locked

The process of creating a subscription began in the previous order.

If an order is still processing, it will not allow “retrofitting” the creation of a subscription and creating another order until the status of the previous one arrives or a certain lock time has passed.

3.01 Card is blocked

The card issuer bank blocked the card for payments.

Card issuer banks have various logics to block risky transactions:

• Limit on online payments
• Daily limit on payments amount
• Daily limit on the number of payments
• Limits for payments with 3DS authorization

It is necessary to explain to the user that the issuing bank is blocking the transaction. Most likely, one of the card limits is triggered. The customer can contact the bank’s support service and ask to remove the limit in question to make the payment. You can also recommend the user try to pay again. For many banks, the rules are not static but triggered based on a scoring system, and repeated attempts to conduct a transaction increase the likelihood of a transaction going through.

3.02 Insufficient funds

The user’s card balance has insufficient funds.

Kindly suggest to the user another card or top-up the current one.

3.03 Payment amount limit excess

Card payment/credit limit was reached.

Card issuer banks have various logics to block risky transactions:

• Limit on online payments
• Daily limit on payments amount
• Daily limit on the number of payments
• Limits for payments with 3DS authorization

It is necessary to explain to the user that the issuing bank is blocking the transaction. Most likely, one of the card limits is triggered. The customer can contact the bank’s support service and ask to remove the limit in question to make the payment. You can also recommend the user try to pay again. For many banks, the rules are not static but triggered based on a scoring system, and repeated attempts to conduct a transaction increase the likelihood of a transaction going through.

3.04 The transaction is declined by the issuer

Contact the card issuer to determine the reason.

Card issuer banks have various logics to block risky transactions:

• Limit on online payments
• Daily limit on payments amount
• Daily limit on the number of payments
• Limits for payments with 3DS authorization

It is necessary to explain to the user that the issuing bank is blocking the transaction. Most likely, one of the card limits is triggered. The customer can contact the bank’s support service and ask to remove the limit in question to make the payment. You can also recommend the user try to pay again. For many banks, the rules are not static but triggered based on a scoring system, and repeated attempts to conduct a transaction increase the likelihood of a transaction going through.

3.05 Call your bank

Contact card issuer for clarifications.

Card issuer banks have various logics to block risky transactions:

• Limit on online payments
• Daily limit on payments amount
• Daily limit on the number of payments
• Limits for payments with 3DS authorization

It is necessary to explain to the user that the issuing bank is blocking the transaction. Most likely, one of the card limits is triggered. The customer can contact the bank’s support service and ask to remove the limit in question to make the payment. You can also recommend the user try to pay again. For many banks, the rules are not static but triggered based on a scoring system and repeated attempts to conduct a transaction increase the likelihood of a transaction going through.

3.06 Debit card not supported

The card has been declined for an unknown reason.

Kindly suggest using another card.

3.07 Card brand is not supported

The card has been declined for an unknown reason.

Kindly ask the user to use another card, the one specified in your payment form.

3.08 Do not honor

The card has been declined for an unknown reason.

The customer should contact their card issuer for more information. More likely the next attempt will be successful.

3.09 3D-Secure authentication required

This transaction should only go through 3D.

Kindly ask the user to try one more time or suggest to the user to use another card.

3.10 Suspected fraud

The issuing bank blocked the transaction due to possible fraud. The card wasn’t in use for a long time, unusual activity, etc.

The customer should contact their card issuer for more information. More likely the next attempt will be successful.

3.11 Recurring payment cancelled

The next subscription payment via this card is not allowed. The customer has blocked future recurring payments.

Kindly ask the user (the customer) why they have blocked subscription payments. If this action was not taken by the customer, they will need to contact their card issuer for more information.

4.01 Card is in a black list

The card is on the blacklist.

Show general decline to the customer. It is best to check the customer for fraudulent activity.

4.02 Stolen card

The card in use is stolen, all transactions are restricted.

Show general decline to the customer. It is best to check the customer for fraudulent activity and block if necessary.

4.03 Restricted card

The card cannot be used to make this payment (it is possible it has been reported lost or stolen). A Restriction is placed at the BIN or cardholder level to restrict usage in a particular country.

• Used when a transaction is attempted from a country where transactions are restricted including OFAC or embargoed countries.
• Restriction may be temporary or permanent.
• Should not be used for non-geographic account restrictions.

Recommendations

• Kindly suggest using another card.
• Do not immediately reattempt.
• Merchant may reattempt if the cardholder confirms the restriction has been removed.
• Merchants and acquirers must not alter country code or other transaction data to gain approval.

4.04 Lost card

The card in use is lost, all transactions are restricted.

Show general decline to the customer. It is best to check the customer for fraudulent activity and block if necessary.

4.05 PSP fraud

The acquiring bank blocked the transaction due to possible fraud. The card wasn’t in use for a long time, unusual activity, etc.

Show general decline to the customer. It is best to check the customer for fraudulent activity and block if necessary.

4.06 Blocked by Country/IP

Blocked by IP mismatch or dye to a high-risk country IP.

Show general decline to the customer. It is best to check the customer for fraudulent activity and block if necessary.

Otherwise, kindly suggest to the customer to try one more time.

4.07 Trusted antifraud system

An antifraud rule was triggered.

Show general decline to the customer. It is best to check the customer for fraudulent activity and block if necessary.Otherwise, kindly suggest to the customer to try one more time.

4.08 AVS mismatch

customer provides a billing address during checkout that does not match the address on file with the card-issuing bank or card company.

Kindly ask the user to enter a valid billing address. If AVS mismatch is recurring for the same user - potential card fraud. Act accordingly to your policies.

4.09 Antifraud service

An antifraud rule was triggered.

Show general decline to the customer. It is best to check the customer for fraudulent activity and block/unblock if necessary.Otherwise, kindly suggest to the customer to try one more time.

5.01 3D secure verification failed

3D Secure verification failed

Show general decline to the customer. It is best to check the customer for fraudulent activity and block if necessary.Otherwise, kindly suggest to the customer to try one more time.

5.02 Invalid Card Token

We received an invalid/nonexistent card token.

Kindly ask the customer to try one more time or to use another card. Please contact Solidgate Support to let us know.

5.03 Application error

Processing error.

Kindly ask the customer to try one more time or to use another card. Please contact Solidgate Support to let us know.

5.04 Merchant is not configured correctly

Processing error.

Please contact Solidgate Support.

5.05 Merchant is not activated yet

Processing error.

Please contact Solidgate Support.

5.06 Duplicate order

The transaction is a duplicate of an earlier transaction and was rejected to avoid charging the same amount twice for the same service.

Prevent a failure when sending a request and a duplicate order is created.

5.07 Exceeded API calls limits

Limit of api requests exceeded.

Send a request without exceeding a certain number of times.

5.08 Invalid transaction

Processing error. The transaction is not authorized due to technical issues.

Kindly ask the customer to try one more time or to use another card. If another card is not an option - kindly suggest contacting the bank.

5.09 Merchant not found

Acquirer error.

Find the merchant through whom the operation is performed in the database.

5.10 Processor does not support requested API method

Acquirer error.

The side communicating with the gateway must send requests through the existing api.

5.11 Invalid routing

Gateway error Payment needs to find the processing card.

The Manufacturers Identification code (MID) where the token is located is enabled and the recurrence cascade (MOTO) is configured.

5.12 Account is blocked

The account is blocked and all transactions made through this account will be declined by the payment processor or acquiring bank until the problem is resolved.

Please contact Solidgate Support.

6.01 Unknown decline code

Unknown Decline Code yet to be mapped.

Kindly ask the customer to try one more time or to use another card. If another card is not an option - kindly suggest contacting the bank.

6.02 Connection error

A connection is poor or interrupted.

Kindly ask the customer to try one more time or to use another card.

7.01 Card token not found

An error occurred and the token was not found.

More likely card is expired. Kindly check exp. date, available in order details - logs, via Solidgate hub. Otherwise, please contact Solidgate Support.

7.02 Google payment error

The payment has been declined via Google Pay.

Please contact Solidgate Support.

7.03 Smart cascade decline

The payment was declined due to the token error on the cascade.

Please contact Solidgate Support.

7.04 3DS cascade to 2D

Processing error.

Please contact Solidgate Support.

7.05 Apple online payment error

The payment has been declined via Apple Pay.

Please contact Solidgate Support.

7.06 Token generation error

Token generation was not successful.

Please contact Solidgate Support.

7.07 SCA engine error

Appears on network_token MIT payments, in case of empty scheme_transaction_id (taken from the first psp transaction)

Please contact Solidgate Support.