| Description | What happened for this alternative payment method. |
| Customer message | What to show the customer. |
| Next step | Recommended merchant action after the decline. |
| Retry The transaction may succeed on a new attempt after refreshing the order or session context. |
| Customer action The customer must update bank or app settings before retrying. |
| Developer action Validate APM request fields, method configuration, or regional availability before retrying. |
| Contact support Requires Solidgate team intervention. Cannot be resolved independently. |
| Do not retry Stop all retry attempts and ask the customer to use a different payment method. |
BLIK Recurring
Boleto
Klarna
Mercado Pago
Pay by Bank
PayPal
Pix
SmartPix
UPI
Payment operations for alternative payments are handled asynchronously. The final result, including any decline, is delivered through a webhook notification or via the check order status endpoint.
When testing decline scenarios, the decline code and final order status appear in those asynchronous updates.
Should you need help with error codes, contact us for assistance.
General decline
Errors reflect declined alternative payment transactions stemming from session timeouts, authentication failures, or customer abandonment.
0.01 General decline
The payment provider or the customer’s bank declined the transaction without a specific reason. Causes can include insufficient funds, the provider’s risk assessment, or the bank blocking the charge.
Soft decline Retry Customer message"Your payment was declined. Please try again or use a different payment method." APM developer action
Retry the payment by creating a new order. If the decline repeats, offer the customer a different payment method.
0.02 Order expired
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.
Soft decline Retry Customer message"Your session has expired. Please try your payment again." APM developer action
Check whether the customer intentionally abandoned the payment. If not, retry by creating a new order and guide them to complete all required actions within the session time window.
Service access
These errors occur when authentication for an alternative payment method fails.
1.01 Authentication failed
This decline covers authentication-related failures, such as an incorrect or expired PIN or one-time code.
Soft decline Retry later Customer message"Authentication failed. Please try again." 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.
Validation errors
These errors indicate invalid alternative payment request data.
2.01 Invalid data/Order not found
This error indicates that required method specific fields are missing or incorrect.
Soft decline Developer action Customer message"The payment request could not be processed. Please check your details and try again." 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 outside the limits of the payment method. For example, a PayPal payment request with a zero amount is declined.
Hard decline Developer action Customer message"The payment could not be processed. Please try again or use a different payment method." APM developer action
Verify that the amount is correctly formatted in minor units and stays within the minimum and maximum amounts of the payment method.
Transaction declines
3.02 Insufficient funds
The customer’s account balance is insufficient to complete the purchase.
Soft decline Customer action Customer message"Insufficient funds. Please add funds to your account or use a different payment method." APM developer action
Ask the customer to add funds or use a different payment method. For subscriptions, retry the charge later according to your retry strategy.
3.03 Payment amount limit excess
The charge amount exceeds the customer’s account limit.
Soft decline Customer action Customer message"Payment amount exceeds the limit. Please check your account limits or contact your bank." APM developer action
Inform the customer that their account limit has been reached. They can change the limit in their banking app or use a different payment method.
3.04 Transaction is declined by issuer
The customer’s bank declined the transaction. For some methods, this also means that the bank does not support the method, for example BLIK Recurring during setup.
Soft decline Retry later Customer message"Your bank declined the payment. Please contact your bank or try a different payment method." APM developer action
Retry after some time. If the customer's bank does not support the payment method, offer a different payment method.
3.05 Call your bank
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.
Soft decline Customer action Customer message"Your bank requires you to call them before this payment can proceed. Please contact your bank and try again." 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.10 Suspected fraud
The customer’s bank blocked the transaction due to suspected fraudulent activity. For BLIK Recurring, the bank could not process the charge as a merchant-initiated transaction without customer authentication.
Hard decline Contact support Customer message"Your payment was declined. Please contact your bank for more information." APM developer action
Advise the customer to contact their bank. If the issue persists, contact us for assistance.
3.11 Recurring payment cancelled
The next subscription or 1-click payment with the recurring token of this payment method is not allowed.
Hard decline Do not retry Customer message"Recurring payment authorization has been cancelled. Please update your payment method to continue." APM developer action
Do not retry the charge. Ask the customer to set up the payment method again to create a new recurring token.
Restrictions or duplicate transactions
4.06 Blocked by country/IP
This code also covers cases where a specific payment method is unavailable or unsupported in the customer’s current location.
Hard decline Contact support Customer message"Your payment was declined. Please try again." 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.
Connection or processing issues
These errors relate to transaction processing issues. Solutions include retrying, using a different payment method, or contacting support.
5.08 Invalid transaction
The payment provider could not process the transaction.
Hard decline Do not retry Customer message"A processing error occurred. Please try again or use a different payment method." APM developer action
Ask the customer to use a different payment method. If the error repeats, contact us for assistance.
Merchant configuration or activation errors
These errors relate to merchant configuration and API communication issues. Ensure proper API method usage, then contact us for assistance if needed.
5.10 Processor does not support requested API method
The processor does not support the requested API method.
Hard decline Developer action Customer message"The payment could not be processed. Please use a different payment method." APM developer action
Use only the API methods that the payment method supports, for example recurring charges only for methods with a recurring token.