Respond to Chargeback Disputes using the API

The process of responding to a Chargeback utilizes the following endpoints:

Required Chargeback Response Headers

Each of the endpoints above will require specific headers:

Responding to a Chargeback

With the steps below, you’ll utilize a combination of Chargeback web alerts to receive updates on changes to the Chargeback process and various endpoints to check the status, respond to, and provide evidence for the Merchant’s Chargeback response:

1. Retrieve the Chargeback ID

2. Find the Chargeback Status (Dispute Stage)

3. Create a chargebackDocument Record for Your Evidence Upload

4. Upload each Evidence File to the associated chargebackDocument Record

5. Submit your Response to the Chargeback’s Status using a Chargeback Message

Step 1: Retrieve the Chargeback ID

After receiving a Chargeback Created web alert, retrieve the Chargeback ID from the Alert and retrieve the value under the disputeId or id parameters shown in the alert response. You can also make a request using

Step 2: Get the Chargeback Status (Dispute Stage)

Using the Chargeback ID you captured from Step 1, make the following API call to find the current status of the Chargeback.

Step 3: Create a Chargeback Document Record for Your Evidence Upload

To prepare the server to accept your file upload and properly associate it with your portfolio and specific chargeback, you must first create a chargebackDocuments record.

Step 4: Upload the File to the associated Chargeback Document Record

Now that you’ve created the chargebackDocument record to associate your file to the specific chargeback, use the steps below to upload each evidence document you wish to upload.

Step 5: Submit your Response using a Chargeback Message

Once each of your evidence files has been uploaded by repeating Steps 4 and 5 above for each document, you’ll submit your response to the current chargeback status using the steps below.

Step 6: Await Issuer Response

After submitting your response and supporting evidence, you’ll need to await a decision from the Issuer. There is no action required while awaiting a decision.

When the Issuer makes a decision based on the evidence provided by the Merchant, a new web alert for Chargeback Won or Chargeback Lost will be sent to notify the Merchant of the decision shown in the disputeStatus field:

• won- The Issuer has reached a decision in favor of the Merchant. This decision can be challenged by the cardholder and escalated to the next Dispute stage.

• lost - The Issuer has reached a decision in favor of the Cardholder. This decision will be final and cannot be challenged by the Merchant.

Step 7: Reaching a Final Issuer Decision

Repeat Steps 2-5 as needed until the Issuer reaches a final decision in the Chargeback process that either:

• The Cardholder accepts and concedes to given the evidence provided by the Merchant, or;

• Has reached the Arbitration stage, resulting in a final, incontestable decision from the third-party card brand network.

Accepting Liability

Merchants can directly accept responsibility for the chargeback due to a fault of their own at any time during the Chargeback cycle during the First Chargeback and Pre-Arbitration dispute stages.

As shown above, you’ll use the same POST /chargebackMessagesendpoint and request method that you did in Step 5, but you’ll change the type parameter value in the request body to acceptLiability.

Checking your Portfolio for Chargebacks

Below are additional API endpoint requests that can be made to check on the general list of all new and existing Chargebacks in your portfolio for a higher-level overview.

There are multiple API endpoint resources associated with Chargebacks, however, all you will generally use is /chargebacks which will return all the necessary results necessary to track the stages of a Chargeback.

Chargeback Response Fields

See a general list of reoccurring Chargeback response body parameters that a Merchant will encounter throughout the Chargeback process:

List all Chargebacks

Use this endpoint to list all Chargebacks under your portfolio with pagination options.

Retrieve a Chargeback by its ID

Use this endpoint to get information about a specific Chargeback within your portfolio using its unique Chargeback ID.

Chargeback Web Alert Notifications

If you haven’t set Chargeback web alerts to be notified, it is recommended that you first set a webhook alert trigger for the following Chargeback events (Dispute Actions):

The below response bodies are examples of what different data each Chargeback Web Alert will provide:

By configuring this Web Alert you’ll be provided with updates about the status of the Dispute as well as the Chargeback ID which will be required to respond to a specific Chargeback using the API.