ACH Return Code Retrieval – Batch Process

For certain gateways (e.g., UnityFi, Fiserv), when ACH payments are rejected by banks, a specialized batch process retrieves and logs return codes (e.g., R01, R07) from the gateway and updates relevant Payment Transaction records in Salesforce.

🛠️ Batch Class: BatchGetTransactionReturnCodes

This batch class:

📡 Fetches ACH return records from the gateway API
📥 Filters transactions by date range based on the gateway’s supported return window
🧾 Updates each matching cm_finance__Payment_Transaction__c record with:

• Return Code (e.g., R01, R07 — if multiple, stored comma-separated)

• Return Code Description (e.g., "R01-Insufficient Funds", "R07-Authorization Revoked")

• Return Date (date when transaction was returned)

🧠 Gateway Time Filter Logic

This batch fetches only those ACH return transactions via API that fall within a valid time window defined by the Payment Gateway record:

• 🔢 Return Time Duration

The number of days (e.g., 7) that a gateway supports for querying return transactions.
The gap between Start Date and End Date for return lookup cannot exceed this duration.

• 📆 Last Return Transaction Processed

This is treated as the start date for the next batch run.
The end date is calculated by adding the return time duration (in days) to this date.
The batch uses this calculated window to fetch all new/unprocessed returns from the gateway.

📆 Return Time Window Processing Logic (Important)

The batch determines which ACH return transactions to retrieve based on two fields configured on the Payment Gateway record:

🔹 Last Return Transaction Processed

This field stores the latest date up to which all ACH return transactions have already been successfully synchronized.

This date becomes the starting reference point for the next batch run.

🔹 Return Time Duration (in days)

This value defines how many days of ACH return data the gateway allows to be queried at a time.

The batch calculates the date range as follows:

So if:

• Last Return Transaction Processed = 5 January

• Return Time Duration = 1

then the batch will query return transactions for: 6 January to 7 January

This results in an effective 2-day window.

ℹ️ Important Notes for Configuration

✔ If you want the batch to retrieve only the next single day of return transactions,
set Return Time Duration = 0
→ This will query only one day beyond the last processed date.

✔ If the batch can process up to 7 days in one run.
Therefore, the maximum allowed Return Time Duration value is 6.

✔ After each successful batch run:

• Last Return Transaction Processed is updated to the End Date

• This ensures the next run continues from where the previous one ended

🔍 Transaction Filtering Logic

• 📌 You can dynamically filter gateway records by using the GetReturnCode_WhereClause in Payment Guru Common Setting (Custom Metadata).

  Example use: Skip disabled gateways, filter by integration type, etc.

⏱️ Automation via Apex Scheduler

• ⚙️ Apex Scheduler supported

• 🗓️ Can be scheduled to run daily, weekly, or at custom intervals

• 🔁 Ensures timely detection of ACH return failures

✅ Benefits

• 📊 Real-time visibility into ACH payment failures

• 🚨 Enables proactive handling of high-risk return codes

• 🔄 Reduces manual effort in reconciliation and compliance follow-up