Error codes

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

An error code is generated for all transactions, successful or not, helping customers understand the transaction outcome and resolve issues. Declined payments can lead to confusion and lost sales, affecting both customers and businesses. By understanding and recognizing these codes, businesses can effectively respond to declined transactions and potentially save the sale.

Refund errors are similar to payment error codes. Detailed information about the reason for the refund failure can be found in the transaction status within the order details in the Solidgate HUB .

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

General decline errors reflect declined transactions due to bank refusals, order time-outs, compliance issues, or authentication failures.

Validation errors indicate that invalid transaction data can typically be resolved by correcting the input data and re-submitting.

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

Fraud and anti-fraud error codes 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 information 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. Resolving these issues involves contacting Solidgate support.

Restrictions or duplicate transactions result from IP blocks, API limits, or routing. Fraud checks, abiding by API limits, and using proper routing are important to avoid them.

Payment system errors arise from payment method inconsistencies, token generation failures, or SCA engine issues, requiring contact with support for assistance.

In this example, the error 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 error code would be to kindly ask the customer to re-enter a valid card number or try using a different card for the transaction.

Should you need assistance when addressing error codes, contact the Solidgate support team.

Decline response example

 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",
    "order_id": "ord_987654321",
    "amount": 100,
    "currency": "USD",
    "status": "fail",
    "decline_code": "2.08"
  }
}

General decline

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

0.01 General decline

The card issuing bank did not complete the transaction successfully.

Recommendations

Ask the customer to retry the payment a few times. Subsequent attempts might be successful.

0.02 Order expired

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

Recommendations

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

This ensures that the payment process is re-initiated and completed within the allowed time.

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

The immediate recommendation is for the customer to attempt the transaction with a different card.

This helps bypass any restrictions associated with the original card.

1.01 Authentication failed

Cardholder authentication was not successful.

Recommendations

Kindly ask the customer to try the payment several times, as subsequent attempts often succeed.

Additionally, ensure that all authentication protocols are correctly implemented and updated to enhance the success rate on retry.

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

Ask the customer to double-check and correct their payment details, ensuring all required fields are complete and accurate. If the issue persists, verify the order's existence and accuracy before reattempting the transaction.

2.02 Invalid amount

This error indicates an issue with the transaction amount, which may be incorrect or exceed allowable limits. It can be triggered by various factors, encompassing incorrect input, transaction limits set by the acquirer or card issuer, or restrictions on specific card types such as prepaid cards.

Recommendations

Advise customers to verify their card details, ensure no limits are set on the card, and contact their card issuer if necessary. If the issue persists, suggest selecting an alternative payment method. Additionally, you can verify that the payment amount is correctly formatted and complies with the acquirer's transaction limits.

2.03 Invalid currency

The currency is not supported.

Recommendations

Verify the supported currencies.

Provide a list of and ensure the transaction uses one of these currencies.

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 number to ensure the has not been cancelled or has already been processed.

It is also important to double-check the order number to ensure accuracy, as a typo or transposition error could also result in this error.

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

If the CVV code error recurs for the same customer, consider the potential for card fraud and advise them to contact their card issuer.

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 that they 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

Ask the customer to double-check and re-enter the card number.

If the problem continues, recommend using an alternative card.

2.09 Invalid expiration date

This error occurs when the card 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 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 the Solidgate support for further assistance.
Card associated with the payment token is expired
As a merchant, you can verify the card 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 the Solidgate support for further assistance.

2.10 Invalid 3DS flow on the merchant side

Guide
3D Secure (3DS) enhances online payment security by adding an extra authentication step for credit and debit card transactions. 3DS URL was not displayed to the cardholder during 3D Secure authentication attempts.

Recommendations

Kindly ask the customer to recall and describe the step-by-step payment flow they experienced.

Ensure that all authentication steps are correctly implemented and visible to the cardholder.

2.11 Invalid 3DS flow on the bank side

The customer went through a payment flow, but the bank did not initiate Guide
3D Secure (3DS) enhances online payment security by adding an extra authentication step for credit and debit card transactions. 3DS authorization.

Recommendations

Kindly ask the customer to try the payment again or suggest using another card.

Ensure that the setup is properly configured and communicate any recurring issues with the bank for further investigation.

2.12 Invalid 3DS flow

Customer hesitated with Guide
3D Secure (3DS) enhances online payment security by adding an extra authentication step for credit and debit card transactions. 3DS authentication.

Recommendations

Kindly ask the customer to try again or suggest they use another card.

Ensure the customer understands the importance of completing the authentication.

2.13 Invalid IP

Incorrect IP address.

Recommendations

Ensure a is passed in the request.

Double-check the IP address format and ensure it corresponds to the customer's actual IP.

2.14 Subscription error

This error indicates an issue with the customer’s subscription, which can happen for various reasons. For instance, it occurs if the customer already has an active Guide
Create and maintain a stable and healthy business subscription model. subscription for that product or when several invoices are in a processing state for the same subscription.

Recommendations

Check the customer’s customer_account_id and their active subscriptions as customer_account_id can have only one active subscription with the same product_id.

Additionally, ensure that you have the correct product_id in your request, as this is an essential parameter for the subscription flow.

Finally, review the number of invoices in a processing state for the customer’s subscription, as up to three payment attempts are allowed.

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

To comply with SCA requirements, retry the transaction using the appropriate 3D authentication process.

Ensure that your payment processing system is configured to support for applicable transactions.

2.16 Subscription is locked

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

Recommendations

Wait until the status of the previous subscription order is resolved or the lock time has expired before attempting to create a new subscription.

To avoid such conflicts, ensure your system properly handles and monitors the status of ongoing creation processes.

2.17 Coupon is not active

The entered coupon is either not valid or not active.

Recommendations

Kindly ask the customer to double-check the and try again or suggest using an alternative, such as an 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 customer 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 the removal of the limit and suggest trying to make the payment again. 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 customer’s card balance has insufficient funds.

Recommendations

Kindly suggest the customer use another card or top up the current one.

Additionally, the customer can split the payment across multiple cards to complete the transaction successfully.

3.03 Payment amount limit excess

The transaction was declined due to the card payment or credit limit being exceeded.

Recommendations

Inform the customer that the card payment or credit limit has been reached. This may be due to various factors, such as online payment limits, daily transaction limits, or authorization limits.

Advise the customer to contact their issuing bank’s support to inquire about and potentially remove any restrictions. Additionally, the customer should 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 customer 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 customer that the issuing bank is likely blocking the transaction because one of the card limits has been 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 customer 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 card type, 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 customer to use another card, the one specified in your .

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, as the decline could be due to various restrictions such as a blocked card, insufficient internet payment limits, security settings, or transaction type limitations.

Advise the customer to verify and resolve any issues with their issuer, including international payment permissions and currency restrictions. Once these are addressed, suggest that the customer retry the transaction, as subsequent attempts may succeed.

3.09 3D-Secure authentication required

The transaction must be processed using Guide
3D Secure (3DS) enhances online payment security by adding an extra authentication step for credit and debit card transactions. 3DS authentication.

Recommendations

Kindly ask the customer to try one more time or suggest to the customer 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 decline could be due to various reasons, such as the card not being used for an extended period, recent unusual activity on the account, and more. The next attempt may be successful after contacting the issuer and addressing the reason for the decline.

3.11 Recurring payment cancelled

This error indicates that the next subscription or a 1-click payment using a recurring token via this payment method is not allowed.

It typically occurs when the customer cancels a Guide
Create and maintain a stable and healthy business subscription model. subscription or revokes authorization for recurring transactions. However, the card issuer may also initiate the decline. Regardless of the source, this decline should never be retried to avoid fees.

Recommendations

Contact the customer to understand why recurring payments were stopped. If the customer did not initiate this action, advise them to check with their card issuer. The issuer may block the recurring payments, for example, due to certain product logic changes on their side.

3.12 Closed user account

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

Recommendations

Kindly ask the customer why they have blocked transactions.

If the customer does not initiate this action, they must 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 a general decline message to the customer to avoid alerting them to the blacklist status. Internally, check the customer for fraudulent activity and review their transaction history for any suspicious patterns.

4.02 Stolen card

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

Recommendations

Show a general decline message to the customer to avoid alerting them to the stolen status. Internally, check the customer for fraudulent activity and block their account if necessary.

4.05 PSP antifraud

The acquiring bank blocked the transaction due to possible fraud.

Recommendations

Show general decline to the customer. The transaction was declined due to potential fraud reasons, the card not being used for a long time, or unusual activity detected. Consider reviewing the customer account for any suspicious activity. If needed, block the card.

4.07 Trusted antifraud system

An antifraud rule was triggered.

Recommendations

Show the customer a general decline to avoid alerting them to the specific antifraud trigger. Internally, check the customer for fraudulent activity and block their account if necessary.

If no fraudulent activity is detected, kindly suggest the customer try the transaction again.

4.09 Antifraud service

An antifraud rule was triggered.

Recommendations

Show a general decline message to the customer to avoid revealing the specific antifraud trigger. Internally, review the customer for any fraudulent activity and block or unblock their account as needed.

If no fraudulent activity is detected, suggest that the customer retry the transaction.

Card blocked or restricted

These errors refer 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 transactions to avoid delays.

4.04 Lost card

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

Recommendations

Show a general decline message to the customer to avoid alerting them to the lost status. Internally, check the customer for fraudulent activity and block their account 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 customer to enter a valid billing address.

If AVS mismatch is recurring for the same customer - potential card fraud. Act according to your policies.

5.01 3D secure verification failed

Guide
3D Secure (3DS) enhances online payment security by adding an extra authentication step for credit and debit card transactions. 3DS 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.

Ensure that the card token generation and handling processes are correctly implemented.

7.01 Card token not found

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

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 or order details in the Solidgate HUB transaction logs.

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.

Ensure your payment system functions correctly and monitor for any recurring issues that may indicate a deeper technical problem.

5.08 Invalid transaction

Processing error.

Recommendations

Please ask the customer to try again or use another card.

If another card is not an option, please suggest contacting the bank.

6.01 Unknown decline code

An unrecognised error 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 the transaction again with the same card or use a different card.

Merchant configuration or activation errors

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

5.04 Merchant is not configured correctly

Processing error.

Recommendations

Verify the settings and configurations to ensure they are correct.

If necessary, consult the documentation for guidance on proper configuration and troubleshooting steps.

5.05 Merchant is not activated yet

Processing error.

Recommendations

Ensure that the merchant account has been fully activated.

If necessary, check with your payment processor to confirm the activation status and follow their procedures to complete the activation.

5.09 Merchant not found

Acquirer error.

Recommendations

Verify that the merchant identifier provided in the transaction request is correct, double-checking for accuracy.

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.

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 why the account is blocked by reviewing account activity, compliance documents, or communication with the acquiring bank. Resolve any issues as required, and then request that the account be unblocked.

Restrictions or duplicate transactions

Errors are due to IP blocks, duplicate transactions, API limits, or routing issues; recommend fraud checks, preventing duplicates, following the 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 that the customer try again.

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

To prevent duplicate orders from being created, prevent a failure when sending a request and implement safeguards to detect and handle duplicate transactions within your system.

5.07 Exceeded API calls limits

Limit of api requests exceeded.

Recommendations

Send requests without exceeding the allowed number of API calls.

For mass operations, use a reasonable rate limiter (10-15 requests per second) to prevent exceeding the limit.

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 cascade setup is correctly configured. Regularly audit your payment gateway settings for accurate routing configurations.

Payment system errors

For errors arising from payment method inconsistencies, cascade disruptions, token generation failures, or SCA engine issues, please seek assistance from the 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 .

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 to ensure successful transactions.

7.04 3DS cascade to 2D

Processing error.

Recommendations

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

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 .

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.

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

Ensure all parameters are correctly passed.

Looking for help? Contact us

Stay informed with Changelog