| Description | One-sentence explanation of what happened. |
| Customer message | What to show the customer. |
| Next step | Defines the recommended action path after the decline. |
⚠ Scheme retry limits. All retries must comply with card scheme rules. Visa allows a maximum of 15 attempts per card within 30 days. Mastercard allows a maximum of 10 attempts within 30 days for recurring transactions. Excessive retries may result in scheme fines. Track retry counts per card.
Payment operations are handled asynchronously. The final result, including any decline, is delivered later through a webhook notification or via the check order status endpoint.
When testing decline scenarios with test cards, the decline code and final order status appear only in those asynchronous updates.
Should you need help with error codes, contact us for assistance.
General decline
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.
"Your payment was declined. Please try again or use a different payment method." Developer action
Retry the same card up to 3 to 4 times with a delay between attempts, for example, retry after 1 hour, then after 24 hours. Track total attempts per card to stay within scheme retry limits.
0.02 Order expired
The payment was not completed within the allocated timeframe, leading to the order’s expiration.
"Your session has expired. Please try your payment again." Developer action
Create a new order and redirect the customer to the payment flow. This ensures the payment process is re-initiated and completed within the allowed time. APM description
This typically means the customer did not complete the payment or the required actions within the allowed time window. In most cases, this is attributed to customer abandonment. APM developer action
Check whether the customer intentionally abandoned the payment. If not, create a new order and guide them to complete all required actions within the session time window.
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.
"Your payment was declined. Please use a different card." Developer action
The transaction is blocked due to compliance or legal restrictions associated with the card or its issuing country. Flag the transaction for internal review.
0.04 Payment declined by routing rules
Payment was declined according to the merchant’s routing configuration.
"This payment was declined due to merchant security settings or routing rules. Please contact the support team." Developer action
Treat this decline as expected behavior from your configured routing logic.
Service access
These errors occur when the merchant account lacks active permissions or service access.
1.01 Authentication failed
Cardholder authentication was not successful.
"Authentication failed. Please try again." Developer action
Retry the payment a few times - subsequent attempts often succeed. Ensure all authentication protocols are correctly implemented and up to date to improve the success rate on retries. APM description
This decline covers authentication-related failures, such as an incorrect or expired PIN or one-time code. APM developer action
Ask the customer to retry the authentication process, ensuring they enter a valid and unexpired PIN or one-time code. If the issue persists, advise them to reset their credentials or contact their payment provider.
1.02 Access denied
The error indicates that the service is not allowed for the account.
"This payment action is not available for this account." Developer action
This is an access/permissions restriction, not a transient error. Verify contract scope and account permissions, then contact support to enable the required service.
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, error object, of the response.
"The payment request could not be processed. Please check your details and try again." Developer action
Validate request payload fields. APM description
This error indicates that required method specific fields are missing or incorrect. Each payment method has unique validation requirements. APM developer action
Validate all APM specific required fields before submission. Refer to the relevant payment method documentation to ensure all required parameters are correctly provided.
2.02 Invalid amount
This error indicates an issue with the transaction amount, which may be incorrect or exceed allowable limits.
"Payment amount exceeds the limit. Please check card limits or contact your bank." Developer action
Verify that the payment amount is correctly formatted and complies with acquirer transaction limits. If customer-entered, ask them to verify their card details and ensure no limits are set on the card. If limits are the issue, suggest an alternative payment method.
2.03 Invalid currency
The currency is not supported.
"This payment method does not support the selected currency. Please use a different payment method." Developer action
Do not retry with the same currency.
2.04 Card brand is not supported
This error occurs when a payment flow is not supported by a specific card brand.
"This card type is not supported for this payment. Please use a different card." Developer action
Verify that the card brand is supported for this specific payment flow. For example, estimated incremental authorization is only available for certain card brands. Display accepted card brands on the payment form to prevent this at input.
2.05 Order not found
This error can occur for a variety of reasons, such as when an order is cancelled or already processed, or when the provided order number is incorrect.
Check the order status the order may be cancelled or already processed. Double-check the order number for typos. Do not retry on a non-existent order ID.
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 Amex.
"The security code (CVV) you entered is incorrect. Please re-enter your CVV and try again." Developer action
Ask the customer to re-enter their CVV. If the error recurs for the same customer across multiple attempts, consider this a potential card fraud signal and advise them to contact their card issuer.
2.07 Request is empty
Information being sent to initiate the payment is incomplete or missing.
"Something went wrong with your payment. Please try again." Developer action
Fix the Solidgate API request to include all required fields. Verify required fields are populated and that the customer's session is active. Confirm the customer remains on the payment page before submission.
2.08 Invalid card number
This decline indicates that the entered card number is incorrect and that the customer’s account cannot be found.
"Invalid card number entered. Please check and try again." Developer action
Ask the customer to verify and re-enter their card details. The card may have been closed or is no longer valid. The cardholder's account may have changed, such as the issuance of a new card. If the issue persists, suggest using an alternative payment method.
2.09 Invalid expiration date
This error occurs when the entered or stored card expiration date is invalid or has already passed.
"Invalid card expiry date. Please verify month and year." Developer action
Ask the customer to verify and confirm the card expiration date. If the card is expired, suggest using a different card for the payment.
2.10 Invalid 3DS flow on merchant side
3DS URL was not displayed to the cardholder during 3D Secure authentication attempts.
"Authentication failed. Please try again." Developer action
Ensure that all 3DS authentication steps are correctly implemented and the 3DS URL is properly rendered to the cardholder. Ask the customer to describe the payment flow they experienced to identify where the 3DS step was missed.
2.11 Invalid 3DS flow on bank side
The customer went through a payment flow, but the bank did not initiate 3DS authorization.
"Authentication failed. Please try again or use a different card." Developer action
Ask the customer to retry the payment. Ensure that the 3DS setup is properly configured. If the issue persists, suggest using another card.
2.12 Invalid 3DS flow
Customer hesitated with 3DS authentication.
"Authentication was not completed. Please try again and confirm the payment in your banking app." Developer action
Ensure the customer understands they must complete the 3DS step without closing the pop-up or app. If the issue persists, suggest using another card.
2.13 Invalid IP
Incorrect IP address.
Ensure a valid IP address 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.
Verify customer account id and product id, and retry only if there is no active subscription or pending invoices for the same product.
2.15 SCA require 3D authentication
The order was attempted to be processed without 3D verification for EU transactions that require 3DS authentication.
"Additional verification is required to complete this payment. Please try again." Developer action
To comply with SCA requirements, retry the transaction using the appropriate 3D authentication process. Ensure 3DS is enabled for EU traffic.
2.16 Subscription is locked
The process of creating a subscription began in the previous order.
Subscription is currently pending confirmation of the previous transaction. Developer action
Wait until the status of the previous subscription order is resolved or the lock time has expired before attempting to create a new subscription. Ensure your system properly handles and monitors the status of ongoing subscription creation processes.
2.17 Coupon is not active
The entered coupon is either invalid or inactive.
"The coupon code you entered is not valid or has expired. Please check the code and try again." Developer action
Validate coupon status before submission, or handle this error gracefully by prompting the customer to enter a valid coupon or proceed without one.
2.18 Invalid product ID
The specified product ID cannot be found.
Ensure that the product ID is correct and the product is active. Check the product information in the Solidgate Hub or use retrieve product details.
Transaction declines
Transaction declines arise from factors such as card limits, insufficient funds, or fraud concerns, often necessitating contact with the bank or alternative payment methods.
3.01 Card is blocked
The card-issuing bank has blocked the card for payments, likely due to triggering one of the card limits such as limits on online payments, daily payment amounts, number of payments, or 3DS authorization limits.
"Your card has been blocked by your bank. Please contact your bank to resolve this, then try again." Developer action
Inform the customer that their card has been blocked by the issuing bank, likely due to a limit being triggered. Encourage them to contact their bank's support service to request the removal of the limit. Retry may succeed after the bank lifts the block.
3.02 Insufficient funds
The customer’s account balance is insufficient to complete the purchase.
"Insufficient funds. Please use a different card or add funds to your account." Developer action
Suggest that the customer use a different card or add funds to the current one. For subscriptions, consider applying retry strategies to automatically apply a discount if the last payment attempt was declined.
3.03 Payment amount limit excess
The transaction was declined because the card payment or credit limit was exceeded.
"Payment amount exceeds the limit. Please check card limits or contact your bank." Developer action
Inform the customer that the card payment or credit limit has been reached. This may be due to online payment limits, daily transaction limits, or 3DS authorization limits. Advise them to contact their issuing bank or retry after the limit resets.
3.04 Transaction is declined by issuer
The card issuer declined the transaction.
"Your bank declined the payment. Please contact your bank or try a different card." Developer action
Retry after some time. The issuer may have blocked the card due to exceeding one or more limits. Many banks use dynamic scoring systems where repeated attempts can increase the chances of approval. Inform the customer that their issuer has blocked the card and advise them to contact their bank's support team.
3.05 Call your bank
The card issuer has blocked the transaction for reasons that need to be clarified.
"Your bank requires you to call them before this payment can proceed. Please contact your bank and try again." Developer action
Inform the customer that the issuing bank is likely blocking the transaction because a card limit has been triggered. Encourage them to contact their bank's support service and suggest retrying after the issue is resolved. APM description
In some cases, the decline may occur because the customer has not enabled the relevant payment method in their account settings. They should check and update their settings accordingly. APM developer action
Ask the customer to verify that the payment method is enabled in their bank or app settings and update it if needed. If the issue persists, suggest contacting their bank's support or trying a different payment method.
3.06 Debit card not supported
The transaction was declined because debit cards are not supported.
"Debit cards are not accepted for this payment. Please use a credit card." Developer action
Advise the customer to use a credit card or other supported payment method. Consider filtering or labeling card type options on the payment form.
3.07 Card brand is not supported
The transaction was declined because the card’s brand is not supported.
"This card brand is not accepted. Please use one of the supported cards." Developer action
Display accepted card brands on the payment form. Ask the customer to use a supported card brand.
3.08 Do not honor
A general decline response indicates that the card issuer has rejected the transaction without providing a specific reason code. This is one of the most common decline responses and can occur due to multiple underlying issues that require verification with the issuing bank.
"Your payment was declined. Please try again or contact your bank." Developer action
Retry 1 to 2 times. If still failing, suggest a different payment method. The decline may result from restrictions such as a blocked card, low 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. Subsequent attempts may succeed.
3.09 3D Secure authentication required
The transaction must be processed using 3DS authentication.
Use 2.15 SCA require 3D authentication for transactions requiring 3D Secure authentication.
"Additional verification is required. Please try again." Developer action
Retry the transaction with 3DS authentication.
3.10 Suspected fraud
The issuing bank blocked the transaction due to suspected fraudulent activity.
"Your payment was declined. Please contact your bank for more information." Developer action
The issuer has flagged the transaction as suspicious. Possible causes include extended card inactivity, unusual account activity, or a compromised card. Advise the customer to contact their card issuer. Contacting the issuer and addressing the root cause may help ensure future transactions are approved.
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.
"Recurring payment authorization has been cancelled. Please update your payment method to continue." Developer action
Retrying can incur scheme fees. 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. Update or replace the payment token with the customer's fresh card details.
3.12 Closed account
The customer has blocked transactions via this card for reasons that require clarification or the account is closed and all transactions are restricted.
"Your payment was declined. Please contact your bank or use a different card." Developer action
Ask the customer if they know any reason for the blocked transactions. Cardholders sometimes request such restrictions for security. Tell the customer to contact their card issuer to confirm the block and lift it, or use an alternative payment method.
3.13 Cancelled by user
This error is returned when the customer explicitly terminates the payment flow.
"Payment was cancelled. Please try again and keep the payment window open until the process is complete." Developer action
Allow the customer to retry. Remind them to complete the 3DS step without closing the pop-up or navigating away from the checkout. If the issue repeats, suggest using another payment method.
Fraud and anti-fraud
Errors signal suspected fraud, blocklisted or stolen cards, antifraud hits. Show a generic decline and investigate, or ask the customer to retry.
4.01 Card is in black list
The payment card being used is listed on a security blocklist, often due to prior suspicious or fraudulent activities.
"Your payment was declined. Please use a different payment method." Developer action
Show a generic decline message. Do not reveal the blocklist status. Internally, check the customer for fraudulent activity and review their transaction history for suspicious patterns. Block the account if necessary.
4.02 Stolen card
The card in use is stolen, all transactions are restricted.
"Your payment was declined. Please use a different payment method." Developer action
Show a generic decline message. Do not reveal the stolen card 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.
"Your payment was declined. Please use a different payment method or contact your bank." Developer action
Review the customer's account for suspicious behavior. The transaction may have been flagged due to possible fraud, extended card inactivity, or unusual activity. If necessary, block the card to prevent further payment attempts.
4.07 Trusted antifraud system
The transaction was blocked by the platform’s internal antifraud rules based on risk scoring signals.
"Your payment was declined. Please try again or use a different payment method." Developer action
Show a generic decline. Do not reveal the antifraud trigger. Internally, review the customer's transaction history for fraud signals and block the account if necessary. If no fraudulent activity is detected, you may allow the customer to retry once.
4.09 Antifraud service
The transaction was blocked by a connected third-party antifraud service based on its risk assessment rules.
"Your payment was declined. Please try again or use a different payment method." Developer action
Show a generic decline. Do not reveal the antifraud trigger. Consult the antifraud service logs or reports to identify the specific rule that was triggered. Internally, review the customer's activity and block or unblock the account based on your findings.
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 as lost or stolen. It may also be restricted at the BIN or cardholder level, such as limits on usage in certain countries subject to OFAC or embargo restrictions. This restriction may be temporary or permanent.
"Your card has certain restrictions. Please contact your bank for details or use a different card." Developer action
Advise the customer to contact their card issuer to clarify the reason for the restriction and whether it is temporary or permanent. In the meantime, suggest using an alternative payment method.
4.04 Lost card
The card in use is lost, all transactions are restricted.
"Your payment was declined. Please use a different payment method." Developer action
Show a generic decline. Do not reveal the lost card status. Internally, check the customer for fraudulent activity and block their account if necessary.
Data or card verification
These errors relate to address mismatch, failed 3DS, or token issues. Verify details, check for fraud, and contact support.
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.
"The billing address you entered does not match your card records. Please verify your billing address and try again." Developer action
Ask the customer to enter a valid billing address. If AVS mismatch is recurring for the same customer, treat this as a potential card fraud signal and act according to your fraud policies.
5.01 3D secure verification failed
3DS verification failed.
"Authentication failed. Please try again." Developer action
Check for potential fraudulent activity and take appropriate action if necessary. If no concerns arise, encourage the customer to retry. Verification failures can sometimes be temporary.
5.02 Invalid card token
An invalid or nonexistent card token was received during the transaction.
"Unable to process your saved card. Please re-enter your card details." Developer action
Ask the customer to retry the transaction or use a different card. Ensure that the card token generation and handling processes are correctly implemented. You may need to re-collect card details from the customer.
7.01 Card token not found
This error indicates that the card token is missing or inaccessible.
"Unable to process your saved card. Please re-enter your card details." Developer action
The most common cause 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. Re-collect card details from the customer if the token is no longer valid.
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.
"A temporary error occurred. Please try again." Developer action
Retry the transaction automatically. Log for monitoring. If this error occurs frequently, investigate the root cause.
5.08 Invalid transaction
Processing error.
"A processing error occurred. Please try again or use a different card." Developer action
Ask the customer to try again or use another card. If another card is not an option, please contact us for assistance.
6.01 Unknown decline code
An unrecognized error code was received during the transaction.
"Your payment was declined. Please try again or use a different card." Developer action
Retry 1 to 2 times with a short delay. If the issue persists, please contact us for assistance.
6.02 Connection error
There is a connection issue, possibly due to poor or interrupted connectivity.
"A connection error occurred. Please try again." Developer action
Retry immediately with exponential backoff. Check network connectivity and ensure your integration can gracefully handle transient connection failures.
6.03 Processing issue
The payment failed due to a technical issue.
"A processing error occurred. Please try again." Developer action
Retry the transaction with the same card or suggest using a different card.
Merchant configuration or activation errors
These errors are related to merchant configuration and API communication issues. To resolve them, contact us for assistance but prior ensure proper API method usage.
5.04 Merchant is not configured correctly
The merchant account configuration is incomplete or incorrect, preventing transaction processing.
Verify the settings and configurations to ensure they are correct. If you need assistance when addressing error codes, contact us for assistance.
5.05 Merchant is not activated yet
The merchant account has not been fully activated and cannot process live transactions.
Ensure that the merchant account has been fully activated. If necessary, contact us for assistance to verify activation status.
5.09 Merchant not found
Acquirer error.
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.
Ensure you communicate with the gateway using only supported Solidgate API methods.
5.12 Account is blocked
The account is blocked and all transactions made through this account be declined.
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. If necessary, contact us for assistance to verify activation status.
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.
"Your payment was declined. Please try again." Developer action
Check the customer for fraudulent activity and block if necessary. The IP may be from a high-risk or blocked country. Review your fraud and geographic restriction policies. APM description
This code also covers cases where a specific payment method is unavailable or unsupported in the customer's current location. APM developer action
Verify whether the selected APM is supported in the customer's region. If it is not available, suggest an alternative payment method that is accessible in their location.
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.
Implement idempotency by using unique order IDs for each transaction attempt. Add safeguards to detect and handle duplicate submissions, particularly on payment form re-submissions or page reloads.
5.07 Exceeded API calls limits
Limit of API requests exceeded.
Implement exponential backoff before retrying. For mass operations, use a rate limiter within the allowed thresholds: Live mode: 100 read/write operations per second, Test mode: 25 read/write operations per second.
5.11 Invalid routing
The gateway could not find a valid processing route for this transaction.
Ensure the MID associated with the transaction is enabled and the MOTO cascade setup is correctly configured.
Payment system errors
For errors arising from payment method inconsistencies, cascade disruptions, token generation failures, or SCA engine issues, please contact us for assistance.
7.02 Google payment error
The payment has been declined via Google Pay.
"Google Pay payment failed. Please try again or use a different payment method." Developer action
Verify the payment details provided by the customer and ensure they are using a supported payment method within Google Pay.
7.03 Smart cascade decline
The payment was declined due to the token error on the cascade.
Verify that the tokens used in the cascade process are correctly generated to ensure successful transactions.
7.04 3DS cascade to 2D
The 3DS authentication flow cascaded to 2D, but the merchant account does not support non-3DS processing.
Ensure that the merchant account supports 3DS flow.
7.05 Apple online payment error
The payment has been declined via Apple Pay.
"Apple Pay payment failed. Please try again or use a different payment method." Developer action
Verify the payment details provided by the customer and ensure they are using a supported payment method within Apple Pay.
7.06 Token generation error
The process to generate a secure token was unsuccessful, possibly due to system or network issues.
"Unable to complete payment. Please verify your payment details and try again." Developer action
Retry the token generation. Confirm that the payment details provided by the customer are accurate and complete. Check for underlying network or system issues if the error persists.
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.
Ensure all parameters are correctly passed, specifically that
scheme_transaction_id is taken from the first PSP transaction and included in subsequent MIT requests.