Needs Attention Transactions

This document focuses on the identification and management of Needs Attention transactions within Chargebee. These transactions occur when there is a discrepancy between the status recorded in Chargebee and that reported by the payment gateway. Though uncommon, such inconsistencies can arise due to temporary connection issues, processing errors, or other system glitches. In this document, we will explore the causes of these discrepancies and provide detailed steps for resolving and reconciling Needs Attention transactions to ensure the accuracy and integrity of your payment records.

Handling Needs Attention transactions in Chargebee

In Chargebee, transactions labeled with the Needs Attention status indicate a discrepancy between Chargebee's records and the payment gateway's records for that transaction. Chargebee will attempt to automatically reconcile these discrepancies to maintain accurate and consistent transaction records.

Automatic reconciliation in Chargebee

Chargebee can automatically reconcile transactions marked as Needs Attention if either the Gateway Transaction ID (id_at_gateway) or Gateway Transaction Reference is available. It does this by retrieving the transaction details directly from the payment gateway. This process depends on the gateway's ability to provide transaction information based on these identifiers. The complete reconciliation workflow is outlined below:

Reconciliation workflow

Chargebee tries to automatically reconcile the Needs Attention transactions using a daily reconciler process. Let us understand the workflows behind the automated reconciliation process for these transactions:

1. Identify and retrieve Needs Attention transactions:
   • Whenever a Needs Attention transaction is created in Chargebee, it is added to a queue for reconciliation.
   • Every 12 hours, the process retrieves these transactions and prepares them for processing.
2. Fetch gateway transaction response:
   • For each transaction, attempt to fetch the transaction response from the payment gateway using the following parameters:
     • Gateway Transaction ID (idAtGateway): A unique identifier for the transaction in the gateway.
     • Gateway Transaction Reference (orderId): An alternative identifier specific to the transaction request.
     • Date: The date of the transaction, used for time-based queries.
3. If gateway transaction is retrieved: Examine the transaction status at the payment gateway and settle the corresponding Chargebee transaction.
4. If gateway transaction is not retrieved:
   • Send an email to Chargebee's Support team, who forward the request to you (the merchant) for intervention to settle the transaction. Chargebee cannot take further action.
   • The email includes the following transaction details to help you locate the transaction in the gateway dashboard: Transaction External ID, Amount, Currency, Date, Order ID, Customer Handle, Subscription Handle, and Gateway Transaction ID (id_at_gateway).

When automatic reconciliation is not working

In certain instances, Chargebee may lack the Gateway Transaction ID (id_at_gateway) needed to retrieve and reconcile transaction details from the payment gateway. Without this identifier, automatic reconciliation cannot proceed, making manual intervention necessary to ensure Chargebee's records are aligned with those of the gateway.

When the Needs Attention reconciler process generates an email with a list of transactions requiring attention, it is sent to the Owner and Admin email IDs of your site. The email includes a Click here button that directs you to the Transaction List page, where transactions marked as Needs Attention from the last 30 days are pre-filtered for review. The email looks as shown below:

You are required to manually reconcile these transactions as detailed in the following section.

You can reconcile the Needs Attention transactions manually using either of the following methods:

• Reconcile transaction API
• Chargebee App

Reconciling transactions via API

You can use the Reconcile transaction API to update the id_at_gateway (Gateway Transaction ID) and Status for a Needs Attention transaction to be reconciled on par with the gateway.

Reconciling transactions via the Chargebee App

This section involves two sets of steps:

• Locating Needs Attention transactions
• Reconciling transaction

Locating Needs Attention transactions

1. Using the NeedsAttentionDangling filter. Go to the Transactions page and select the NeedsAttentionDangling filter from the All Transactions drop-down menu at the top.

   

2. From the banner on top of the Transactions page. Follow the steps below: a. Log in to the Chargebee app and go to Logs > Transactions. b. When any Needs Attention transactions are created in the last 30 days, a banner appears, indicating that your attention is required. c. Click See Transaction to view the list of all Needs Attention transactions.

   

Reconciling a Needs Attention transaction

Follow the steps below:

1. On the Transactions page, click on the relevant transaction to open the details page.

2. In the right pane, click Update Status.

   

3. On clicking Update Status, the Update Transaction Status popup appears. 4. Enter the Gateway Transaction ID (auto-populated if available) and select the relevant Transaction Status after checking the same in your gateway dashboard.

4. Click Update. The Needs Attention transaction is now reconciled.

   

Frequently asked questions (FAQs)

Question: How should I handle an invoice associated with two transactions, one that requires attention and the other successful?

Answer: If an invoice is linked to two transactions: Transaction 1 – Needs attention Transaction 2 – Successful (which initially moved the invoice to a Paid status)

When Transaction 1 fails at the gateway, updating its status to Failure will move the invoice back to Not Paid.

To correctly move the invoice to Paid status:

1. Remove the Successful transaction from the invoice.
2. Go to the invoice and click Apply Payments.
3. Link the successful transaction again to the invoice.

This process updates the invoice status from Not Paid → Paid and ensures that the invoice status remains accurate without discrepancies.