Respond to Chargeback Disputes using the API
The process of responding to a Chargeback utilizes the following endpoints:
Endpoint | Description |
---|---|
| Used to check on the logged status changes of a Chargeback. |
| Used to create a record on the server for a chargeback document or file upload |
| Used to upload the actual chargeback evidence file, such as document or image, and associate it with the |
| Used to send a Merchant response to an Issuer about a specific Dispute Stage option (Accept Liability or Respond with Evidence). |
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:
Retrieve the Chargeback ID
Find the Chargeback Status (Dispute Stage)
Create a
chargebackDocument
Record for Your Evidence UploadUpload each Evidence File to the associated
chargebackDocument
RecordSubmit your Response to the Chargeback’s Status using a Chargeback Message
The steps below assume you would like to continue to dispute the transaction chargeback for each dispute stage of the chargeback cycle. To accept liability for any chargeback, see the Accepting Liability section below.
Tip: If you’re already familiar with Steps 1-4, visit the response options on Step 5 for specific request bodies for each chargeback response type.
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.
Warning: You must repeat this step for each file you intend to upload. You cannot upload multiple files to a single 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 /chargebackMessages
endpoint and request method that you did in Step 5, but you’ll change the type
parameter value in the request body to acceptLiability
.
Dispute Stage | Request Body |
---|---|
First Chargeback | |
Pre-Arbitration | |
Arbitration |
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):
Alert Trigger | Description |
---|---|
| A new Dispute has been created through retrieval. |
| A First Chargeback has been initiated by a Cardholder’s issuer. |
| A Chargeback was decided by the Issuer in favor of the Merchant. |
| A Chargeback was decided by the Issuer in favor of the Cardholder. |
| A final decision has been reached and the Chargeback process has been closed. |
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.