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.

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.

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.

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

Error override customizations

All gateway-related error causes are associated with properties that drive system behavior. Error overrides let you change how Chargebee treats a standardized gateway error for your site when the default setting does not match your recovery strategy.

The primary overridable property is Retryable. This determines whether Chargebee should retry a failed payment as part of the dunning process. For example, you can mark an error as non-retryable when retries are unlikely to succeed and you want Chargebee to move to the next dunning action sooner.

Depending on what is enabled on your site, you can configure error overrides via: Error Handling Settings : Override retryability at the error ID level or for a specific matching condition, and review how errors map from gateway responses to Chargebee error IDs.

Set up error overrides at gateway error code level

Use Error Handling Settings when you want to override retryability at the error ID level or for a specific matching condition.

In Error Handling Settings, you can configure retryability at two levels:

• Retryable at error ID level: Applies one retryable setting to all matching conditions under a Chargebee Error ID.
• Retryable at rule level: Applies a retryable setting to a specific matching condition, such as a gateway error code or message.

The Error Handling Settings page also displays whether error messages under an error ID are exposed in customer failure emails. This helps you understand the customer-facing impact while reviewing retry settings.

1. Identify the error you want to configure. You can start from a failed transaction and note the Chargebee Error ID, gateway error code, or error details.

2. Go to Settings > Configure Chargebee > Error Settings to open Error Handling Settings.
   You can also use https://<your-site>.chargebee.com/error_settings.

3. Select the error group. Gateway errors are listed under Gateway.

4. Use Gateways, Status, or Search to find the error ID or matching condition you want to review.

   

5. Review the row details:

   • Chargebee Error ID: Standardized Chargebee error classification.
   • Retryable at error ID level: Retry setting that applies across matching conditions under the error ID.
   • Gateway: Payment gateway for which the condition applies.
   • Matching rules: Gateway conditions, such as error code or message, that map a gateway response to the Chargebee Error ID.
   • Retryable at rule level: Retry setting for the selected matching condition.

6. Choose the override scope:

   • Use Retryable at error ID level to apply the same setting to all matching conditions under that error ID.
   
   • Use Retryable at rule level to update only the selected matching condition.
   

7. Turn retry on or off, then confirm the change in the dialog.

8. Click Apply to save the change. To cancel unapplied changes, click Discard.

9. Verify that the row shows Overridden and review the Last updated on value.

Changes apply to future transactions that match the configured error ID or matching condition.

To revert an override, change the retryable setting back to the default value and click Apply.

Viewing Payment Errors in your Chargebee site

You can view detailed error information directly on the Transaction Detail page.

For each transaction, the following error information is displayed when applicable:

• Error: The error message returned by the payment gateway or integration.
• Error Resolution: Suggested steps to resolve the issue, along with a link to the relevant error definition in Chargebee for additional context and troubleshooting.
• Error Details: Comprehensive information about the error, including the reason for the failure or decline, to help you quickly identify and resolve payment issues.

Chargebee can show the default platform retryability and the configured retryability (if overridden). If an override affected the outcome, you can open the related error override from the transaction details page to review the matching error ID or override setting. Platform vs. configured retryability on the transaction details page and the Affected by Error Override filter on the Transactions index are available.

Find impacted transactions

Use the Transactions index to review failed payments where an error override changed retryability from the Chargebee platform default. This helps you validate override settings, audit dunning behavior, and spot transactions that would have been retried (or not retried) differently without your configuration.

A transaction appears in this list when the configured retryability (after your error override setting is applied) differs from the platform default for that error.

To find these transactions:

1. Go to Logs > Transactions.
2. Use either of the following:
   • Open the Affected by Error Override - This Month preset segment.
   • Add a filter: Affected by Error Override is Yes, then adjust the date range if needed.
3. Open a transaction from the list to review error details, platform vs. configured retryability, and a link to the related error override setting when available.

Frequently Asked Questions (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.

5. When should I override retryability at the error ID level instead of for a specific matching condition?

   Override at the error ID level when the same retryable behavior should apply to all matching conditions under that Chargebee Error ID. Override for a specific matching condition when only a particular gateway error code or response needs different retry behavior.

6. Why do I see the “invalid or missing payment information” error when adding UK Direct Debit (BACS) in the Portal?

   This error occurs when required BACS payment details are missing or invalid in the Portal. It is triggered by client-side validation in chargebee.js, which prevents the request from being sent to Chargebee or Stripe until all mandatory fields are correctly provided.

   To resolve this, ensure the following details are properly collected and configured:

   Customer details:

   • Person: First name and last name, or Company: Company name
   • Email (required)

   Billing address:

   • Address line 1
   • City
   • Country code (must be GB for UK Direct Debit)
   • Zip (postcode)

   Bank account:

   • Sort code (6 digits)
   • Account number (8 digits)

   Additionally:

   • Enable all required billing fields for BACS in the Portal configuration
   • Ensure all required fields are displayed in the Portal UI
   • Validate the formats of the sort code and account number

   Providing all mandatory details correctly will prevent this error and allow successful setup of UK Direct Debit (BACS).