Dispute / Chargeback Reconciliation Guide

📰
Overview
This guide walks through pulling chargeback cases and tracing each disputed transaction back to its original sale in the batch reports — the core reconciliation loop for resolving disputes. It covers two paths: reconciling at the Merchant Account level, or at the Agent/Partner level across multiple merchants. By the end, you'll be able to match a disputed transaction from a chargeback case to the actual sale record, with the fields needed to build a dispute response.

Prerequisites

Before you begin, make sure you have:

A valid Bearer token for either Merchants or Agents/Partners
For Agent/Partner reconciliation: an Agent/Partner-level secret key
The date range you want to reconcile (chargeback report dates and batch settlement dates)

Step 1: Export Chargeback Data

Pull the chargeback cases for a given reporting window. This gives you the disputed transactions you'll later match against original sales.

To get a list of disputes, see the API Reference: here

What you get back: A list of chargeback cases filtered by report_date, which you'll reconcile against batch transaction records in the following steps.

💡
Tip: Note that the date format for this endpoint is YYYY/MM/DD.

From here, follow Step 2: Option 1 if reconciling a single Merchant Account, or Step 2: Option 2 if reconciling at the Agent/Partner level.

Step 2: Retrieve Corresponding Information

The method of reconciliation determines the next steps.

Option 1: Retrieve Transaction Details

If you are looking to reconcile at the Merchant Account level, you must retrieve Transaction Details. Pull the batch transaction details for a specific date to find the original sale. Refer to the curl statement below to accomplish this.

What you get back: Individual transaction batch details for that merchant, which you match against the disputed transactions from Step 1.

curl --location 'https://api.payarc.net/v1/batch/reports/details?date=2025-04-03' \
--header 'accept: application/json' \
--header 'authorization: Bearer YOUR_SECRET_KEY'

💡
Tip: This endpoint uses the batch date, which may differ from the transaction date by a few days. Skip this step if you're reconciling at the Agent/Partner level.

Option 2: Retrieve Batch Reports by Date Range (Agent / Partner)

Step 2A: List Batches Within Desired Date Range

If you are looking to reconcile at the Agent/Partner level across multiple merchants, list the batches within a date range. This gives you the identifiers needed to drill into individual transactions.

To get a list of agent batches within a date range, see the API Reference: here

What you get back: Batch records including Batch_Reference_Number and Merchant_Account_Number — both required to retrieve the full transaction breakdown in Step 2B.

💡
Tip: This endpoint uses a different date format than that in Step 1. The format is YYYY-MM-DD.

💡
Tip: The reporting window spans three calendar months — the month of to_date plus the two months before it. from_date must be on or after the first day of the month two months before to_date. For example, if to_date is 2025-08-26, then from_date must be 2025-06-01 or later; if to_date is 2025-03-15, then from_date must be 2025-01-01 or later. When to_date is the last day of a month, the boundary may land one month later than that. If from_date falls outside the window, the API returns a 422 naming the earliest date it will accept.

Step 2B: Get Detailed Transaction Record by Batch & Merchant (Agent / Partner)

Using the Batch_Reference_Number and Merchant_Account_Number from Step 2A, query the full breakdown of every transaction in that batch to locate the disputed sale.

To retrieve detailed transaction information for a batch report, see the API Reference: here

What you get back: Full transaction records for every sale in the batch. The fields you'll use to match against a chargeback are amount, transaction_date, auth_code, card_number (masked), and acquirer_reference_number.

💡
Tip: acquirer_reference_number is the strongest link between a chargeback and its original sale. Compare it against the acquirer_reference_number on the /cases record from Step 1, then confirm the match with auth_code and transaction_date. Note that the chargeback returns the card as card_number_prefix and card_last4, while the batch record returns a single masked card_number.

💡
Tip: Batch records for payfac accounts do not include acquirer_reference_number. For those merchants, match on auth_code, transaction_date, and amount instead.

💡
Tip: Amounts use different units on each side. Batch amount is in cents; the chargeback's case_amount and merchant_amount are in dollars.

What's Next

Now that you can reconcile chargebacks to their original sales, you can: