Error codes

Understand why the payment is declined and how you can resolve it

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.

Validation errors

Indicate that invalid transaction data can typically be resolved by correcting the input data.

Transaction declines

Transaction declines stem from card limits, or fraud concerns, often requiring bank contact or alternative payments.

Fraud and anti-fraud

Signal potential fraud with blacklisted or stolen cards, necessitating a decline, further investigation, or customer retry.

Card blocked or restricted

Involve blocked transactions due to lost or restricted cards, prompting the need for alternative payment options.

Data or card verification issues

Involve address mismatches, 3D verification failures, and card token issues, requiring customer info checks.

Connection or processing issues

Involve transaction and connection issues, with solutions being retrying, using a different card, or contacting the bank.

Merchant configuration or activation errors

Concern merchant setup and API communication; solutions involve reaching out to Solidgate support.

Restrictions or duplicate transactions

Result from IP blocks, API limits, or routing; advise fraud checks, respecting API limits, and using proper routing.

Payment system errors

For payment method inconsistencies, token generation failures, or SCA engine issues, contact support for assistance.

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

Decline response

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


{
  "error": [
    {
      "code": "2.08",
      "message": "Invalid card number"
    }
  ],
  "transaction": {
    "id": "trn_123456789",
    "status": "fail",
    "amount": 100,
    "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 customer to re-enter a valid card number or try using a different card for the transaction.

General decline

These errors reflect declined transactions stemming from bank refusals, order time-outs, compliance issues, or authentication failures.

0.01 General decline

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

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

0.02 Order expired

The payment was not completed within the allocated timeframe, leading to order expiration. Recommendations

Encourage the customer to reattempt the transaction using the same card.

0.03 Illegal operation (violation of law)

The card issuer may block a transaction due to legal violations, either related to the cardholder or originating from a sanctioned country. Recommendations

Advise the customer to use an alternative card.

1.01 Authentication failed

Cardholder authentication was not successful. Recommendations

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

Validation errors

These errors indicate that invalid transaction data can typically be resolved by correcting the input data.

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.

Recommendations

Kindly contact Solidgate support for assistance.

2.02 Invalid Amount

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

Review the order amount against acquiring bank limits. Adjust or split as needed.

For further queries or assistance, contact Solidgate support.

2.03 Invalid Currency

The currency is not supported. Recommendations

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. Recommendations

To troubleshoot this error, it is recommended to check the order status and the order number, to make sure the order is not cancelled or already processed. Also, it is 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

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. Recommendations

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

If CVV code error is recurring for the same customer - potential card fraud.

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. Recommendations

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.

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 customer entered an incorrect card number. Recommendations

Politely ask the customer to double-check and re-enter the valid card number. If the problem continues, recommend using an alternative card.

2.09 Invalid expiration date

This error occurs when the card’s expiration date entered during the transaction is invalid or has already passed. Recommendations

User enters an invalid expiration date
Request the user to recheck and confirm the card’s expiration date. If the card is indeed expired, advise them to use a different card for the transaction.
In cases where the user is certain of the card’s validity, but the system still flags the expiration date as invalid, recommend contacting Solidgate support for further assistance.
Card associated with the payment token is expired
As a merchant, you can verify the card’s expiration date in the order details via the Solidgate HUB. This will help determine whether the issue is due to incorrect user input or an outdated card linked to the payment token.
If verification via HUB confirms the card is expired or if you are unable to determine the cause, it is advisable to reach out to Solidgate support for further assistance.

2.10 Invalid 3DS flow on the merchant side

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

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. Recommendations

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. Recommendations

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. Recommendations

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. Recommendations

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. Recommendations

Retry the transaction with the appropriate 3D authentication process.

If you are unsure how to do this or if the issue persists, please contact Solidgate support for further guidance.

2.16 Subscription is locked

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

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.

2.17 Coupon is not active

The entered coupon is either not valid or not active. Recommendations

Kindly ask the user to double-check the coupon code and try again, or suggest using an alternative, active coupon.

Transaction declines

Transaction declines arise from factors like card limits, insufficient funds, or fraud concerns, often necessitating bank contact or alternative payment methods.

3.01 Card is blocked

The card-issuing bank has blocked the card for payments, likely due to triggering of one of the card limits such as limits on online payments, daily payment amounts, number of payments, or 3DS authorization limits. Recommendations

Inform the user that their card has been blocked by the issuing bank, likely due to a triggered limit.

Encourage the customer to contact their bank’s support service to request removal of the limit, and suggest trying the payment again, as many banks have dynamic rules based on a scoring system, and repeated attempts can increase the likelihood of successful transactions.

3.02 Insufficient funds

The user’s card balance has insufficient funds. Recommendations

Kindly suggest to the user another card or top-up the current one. Additionally, merchants could allow users to split the payment across multiple cards.

3.03 Payment amount limit excess

Card payment/credit limit was reached. Recommendations

Inform the user that the card’s payment or credit limit has been reached, which may be due to various factors such as online payment limits, daily transaction limits, or 3DS authorization limits.

Advise the user to contact their issuing bank’s support to inquire about and potentially remove any restrictions. Additionally, suggest that the user try the transaction again, as some banks use dynamic scoring systems where multiple attempts could increase the likelihood of success.

3.04 The transaction is declined by the issuer

The transaction has been declined by the card issuer. Recommendations

Inform the user that the transaction was blocked by their card issuer, likely due to one of the card limits being triggered. Reasons for decline can vary, including limits on online payments, daily payment amounts, or daily transaction counts.

Suggest that they contact their bank’s support service to remove the relevant limit or attempt the transaction again, as repeated attempts may increase the likelihood of approval.

3.05 Call your bank

The card issuer has blocked the transaction for reasons that need to be clarified. Recommendations

Inform the user that the issuing bank is likely blocking the transaction due to one of the card limits being triggered.

Encourage the customer to contact their bank’s support service to inquire about any possible limits and request their removal if necessary. Suggest that the user try the transaction again, as repeated attempts may increase the likelihood of success due to some banks using a dynamic scoring system.

3.06 Debit card not supported

The transaction was declined because debit cards are not supported. Recommendations

Advise the customer to use a different type of card, such as a credit card, for this transaction.

3.07 Card brand is not supported

The transaction was declined because the card’s brand is not supported by the payment system. Recommendations

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. Recommendations

Encourage the customer to contact their card issuer for more information. It is likely that the next attempt may be successful once the issue has been addressed with the issuer.

3.09 3D-Secure authentication required

The transaction must be processed using 3D-Secure authentication. Recommendations

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. Recommendations

Advise the customer to contact their card issuer for more information. This could be due to the card not being in use for a long time, unusual activity, etc. It is possible that the next attempt will be successful after the issue has been resolved with the issuer.

3.11 Recurring payment cancelled

The next subscription payment via this card is not allowed. Recommendations

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.

3.12 Closed User Account

The customer has blocked transactions via this card for reasons that require clarification. Recommendations

Kindly ask the user (the customer) why they have blocked transactions. If the customer did not initiate this action, they will need to contact their card issuer for more information.

Fraud and anti-fraud

These errors indicate transactions flagged for potential fraud due to blacklisted cards, stolen cards, or triggered antifraud rules, requiring merchants to display a general decline and conduct further investigation or recommend customers to try again.

4.01 Card is in a black list

The payment card being used is listed on a security blacklist, often due to prior suspicious or fraudulent activities. Recommendations

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. Recommendations

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

4.05 PSP antifraud

The acquiring bank blocked the transaction due to possible fraud. Recommendations

Show general decline to the customer. The card was not in use for a long time, unusual activity, etc. It is best to check the customer for fraudulent activity and block if necessary.

4.07 Trusted antifraud system

An antifraud rule was triggered. Recommendations

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.09 Antifraud service

An antifraud rule was triggered. Recommendations

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.

Card blocked or restricted

These errors pertain to transactions blocked due to lost or restricted cards, requiring merchants to offer alternative payment options and check for potential fraud.

4.03 Restricted card

The card is restricted, possibly due to being reported lost or stolen, or because of a restriction at the BIN or cardholder level preventing usage in certain countries, such as those subject to OFAC or embargo restrictions. This restriction could be temporary or permanent. Recommendations

While resolving the restriction, consider using an alternative payment method for transaction to avoid delays.

4.04 Lost card

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

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

Data or card verification

These errors relate to address mismatches, failed 3D verification, and issues with card tokens, requiring merchants to verify customer information, check for fraud, and consult support as needed.

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. Recommendations

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.

5.01 3D secure verification failed

3D secure verification failed. Recommendations

Show a general decline message to the customer. Check for potential fraudulent activity and take appropriate action if necessary. If no concerns arise, encourage the customer to retry the transaction, as verification failures can sometimes be temporary.

5.02 Invalid Card Token

An invalid or nonexistent card token was received during the transaction. Recommendations

Ask the customer to retry the transaction or use a different card.

If the issue persists, please contact Solidgate support for further assistance.

7.01 Card token not found

This error indicates that the card token is missing or inaccessible.

It occurs in scenarios such as failure to receive data from the tokenization service, or when no card ID is linked to the sptoken to retrieve data from the tokenization service.

Recommendations

The most common cause of this error is the absence or inaccessibility of card payment credentials associated with the token. Verify the card details in the Solidgate hub transaction logs or order details.

If the card data is not retrievable or the issue persists, please contact Solidgate support for assistance.

Connection or processing issues

These errors relate to transaction issues and connection errors; solutions include retrying, using a different card, or contacting the bank.

5.03 Application error

An error occurred during transaction processing. Recommendations

Advise the customer to retry the transaction or use an alternative card.

If the issue persists, contact Solidgate support for assistance.

5.08 Invalid transaction

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

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.01 Unknown decline code

An unrecognised decline code was received during the transaction. Recommendations

Encourage the customer to attempt the transaction again or to use an alternative card. If neither option is viable, advise the customer to consult their bank for more information.

6.02 Connection error

There is a connection issue, possibly due to poor or interrupted connectivity. Recommendations

Request the customer to retry the transaction or consider using a different card.

6.03 Processing issue

The payment failed due to a technical issue on the provider’s or processor’s side. Recommendations

Please, try again with the same card or use a different card.

If the issue persists, please contact Solidgate support for assistance.

Merchant configuration or activation errors

These errors are related to merchant configuration and API communication issues; resolution steps include contacting Solidgate support or ensuring proper API method usage.

5.04 Merchant is not configured correctly

Processing error. Recommendations

Verify the merchant’s settings and configurations.

If necessary, consult the payment gateway documentation or contact Solidgate support for assistance.

5.05 Merchant is not activated yet

Processing error. Recommendations

Ensure that the merchant account has been activated.

If the account status is unclear, please contact Solidgate support for verification and assistance.

5.09 Merchant not found

Acquirer error. Recommendations

Verify that the merchant identifier provided in the transaction request is correct. If the identifier is correct but the merchant still cannot be found, consult the acquirer’s documentation or contact Solidgate support for further investigation.

5.10 Processor does not support requested API method

The processor does not support the selected API method, leading to an error. Recommendations

Ensure you communicate with the gateway using only supported API methods.

If the error arises in response to a zero-amount payment, it indicates that your processors do not support this specific API method, contact Solidgate support for further assistance.

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. Recommendations

Determine the reason for the account being blocked by reviewing account activity, compliance documents, or communication with the payment processor or acquiring bank. Resolve any issues as required, and then request that the account be unblocked.

If you need further assistance or clarification, please contact Solidgate support.

Restrictions or duplicate transactions

Errors are due to IP blocks, duplicate transactions, API limits, or routing issues; recommend fraud checks, preventing duplicates, adhering to API limits, and proper routing.

4.06 Blocked by Country/IP

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

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.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. Recommendations

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

5.07 Exceeded API calls limits

Limit of api requests exceeded. Recommendations

Send a request without exceeding a certain number of times.

5.11 Invalid routing

Gateway error, payment needs to find the processing card. Recommendations

Ensure the MID associated with the transaction is enabled, and the MOTO cascade setup is correctly configured. Regularly audit your payment gateway settings for accurate routing configurations.

If the issue persists, contact Solidgate support for further assistance.

Payment system errors

For errors arising from payment method inconsistencies, cascade disruptions, token generation failures, or SCA engine issues, please seek assistance from Solidgate support.

7.02 Google payment error

The payment has been declined via Google Pay. Recommendations

Verify the payment details provided by the customer and ensure they are using a supported payment method within Google Pay.

If the issue persists, contact Solidgate support for further assistance.

7.03 Smart cascade decline

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

Verify that the tokens used in the cascade process are correctly generated and configured.

If you are unsure how to do this or if the error persists, please contact Solidgate support for further assistance.

7.04 3DS cascade to 2D

Processing error. Recommendations

Ensure that the merchant account supports both 3D Secure and 2D transaction flows.

If the error persists, contact Solidgate support for further investigation.

7.05 Apple online payment error

The payment has been declined via Apple Pay. Recommendations

Verify the payment details provided by the customer and ensure they are using a supported payment method within Apple Pay.

If the issue persists, contact Solidgate support for further assistance.

7.06 Token generation error

The process to generate a secure token was unsuccessful, possibly due to system or network issues. Recommendations

Confirm that the payment details provided by the customer are accurate and complete.

If the error continues, contact Solidgate support for further assistance.

7.07 SCA engine error

Strong Customer Authentication (SCA) engine error occurs during MIT payments if the scheme_transaction_id (taken from the first PSP transaction) is empty. Recommendations

Please contact Solidgate support.

Access to API

Learn to authenticate API requests and fix validation errors effectively.

Integrate

Seamlessly integrate Solidgate into your product using various integration options.

Testing

Simulate payments to test your integration before launching in production.