Payment errors with root cause and troubleshooting

This document contains a structured overview of the various payment error messages encountered in Chargebee. These errors may arise from payment gateways, bank account validations, mandate issues, fraud checks, compliance validations, network, processors, or other sources.

This information aims to help support, product, engineering, and operations teams quickly identify the root cause of a payment failure, determine the appropriate next step, and provide a better customer experience.

Why is this important?

Payment processing is complex and heavily dependent on multiple external systems, such as card issuers, banks, payment gateways, and regulatory bodies. Understanding why a transaction fails is crucial to resolving the issue.

This document standardizes the error messages and explains the following:

• The root cause of the error.
• How to troubleshoot and resolve the error.

This approach helps Chargebee maintain a consistent approach to error handling across teams and touchpoints, including retry logic, customer communication, and system alerts.

How will you use it?

This error documentation serves as a reference for:

• Support teams: To provide accurate, contextual responses to customers.
• Product and engineering teams: To configure dunning strategies and automate retries.
• AI assistants and bots: To interpret and surface relevant solutions to users in real time.

Use case 1: Retryable

Some errors are transient (for example, gateway timeouts, network interruptions) and can be retried. Others (for example, expired cards, invalid credentials) require user intervention before another attempt.

Example:

id: gateway.transaction_processing.low_balance 
retryable: "true"

In this case, the transaction failed due to insufficient funds. Since it's retryable, the smart dunning system may reattempt the charge after a few days or on the customer's next scheduled payment date.

Use case 2: Exposing in customer emails

Some error messages may be too technical, internal, or irrelevant to share with end users. Chargebee uses the exposeInCustomerFailureEmails flag to determine whether an error should be shown in customer-facing emails.

Example:

id: gateway.merchant_account.test_only 
exposeInCustomerFailureEmails: "false"

In this case, the error occurs because the merchant account is still in test mode. Since this is a setup-related issue on the merchant side, not caused by the customer, Chargebee suppresses the detailed error message from customer emails and instead shows a generic message to avoid confusion.

Limitations

• This documentation covers only Chargebee-standardized errors and may not fully reflect gateway-specific return codes.
• Some gateway behaviors, such as fraud thresholds, are out of scope and governed by the processor.
• Error interpretation may vary slightly depending on regional regulations, banking rules, or payment method types (for example, SEPA vs. ACH).
• The messages will not always be the same and will be revised on a case-by-case basis. You should not have any application logic based on them.

Error property overrides

All gateway-related error causes are associated with properties that drive system behavior. Property overrides allow you to customize the system default to match specific business requirements. The following properties are overridable in the gateway error group:

• Retryable

Steps to override:

1. Navigate to Settings > Configure Chargebee > Error Cause Settings.
   Note: Use this URL to land on the settings page: https://demo-test.chargebee.com/error_cause_settings/property_overrides. Replace demo-test with your test or live site's domain name.
2. Click Create Property Override.
3. Select the Error Group as Gateway with other relevant information.
   
4. Click Save.

Getting started

Chargebee provides an error response body in JSON format for all API transactions. One key field in this response is the error_cause_id, a Chargebee-defined optional code that identifies the specific error encountered during the request. This standard code enables consistent error handling across all gateway services.

To resolve payment-related errors, refer to the detailed documentation that categorizes standardized errors and explains their root causes, retryability, and suggested solutions.

Supported error categories:

• transaction_processing
• payment_method
• bank_account
• merchant_account
• identity_verification
• transaction_authorization
• technical
• dispute
• token
• mandate
• fraud
• general
• compliance

FAQs

1. Why should I use smart dunning?

   With Chargebee's Error Intelligence, we can now classify incoming errors from third parties as retryable or not. This property of the error is currently used only in smart dunning, so if you want to fully utilize the value of error intelligence in payments, switch to smart dunning.

2. How are the errors structured and grouped?

   The error ID is a fixed structure that is dot-separated. The first part, error group, mentions which particular integration type or group of errors this belongs to. The second part is the theme of the problem, for example, fraud. The third part is the specifics of the problem. The ID is self-explanatory and will help merchants identify issues quickly in the long run.

3. Will Chargebee stop sending old errors, and will these be the new errors?

   This is a new error field that is provided along with the existing error fields that you already receive. Currently, there are no plans to stop sending old errors.

4. How can I get the actual gateway error code?

   You can retrieve the transaction to view the actual error. There is a field called error_details, as mentioned in the API documentation. You can retrieve the transaction to view the actual error. There is a field called error_details, as mentioned in the API documentation.