Disputes Overview

PayPal merchants, partners, and external developers can use the PayPal Disputes API to manage disputes.

Overview

Occasionally, something goes wrong with a customer's order.

A dispute occurs when:

A customer has not received goods or a service.
The received goods or service are not as described.
The customer needs more details, such as a copy of the transaction or a receipt.

To dispute a charge, a customer can file a case with PayPal through the Resolution Center or ask their bank or credit card company to reverse a charge. A charge reversal is also known as a chargeback.

To manage disputes, you can use the Resolution Center or the Disputes API. With the Resolution Center, you can manually respond to disputes. The Disputes API automates the disputes management process. With the Disputes API, you can list disputes, show dispute details, accept a claim, appeal a dispute, make an offer to resolve a dispute, provide evidence, and send a message to the other party.

In the sandbox, you can also create a dispute, update the dispute status, and settle a dispute. An agent at PayPal normally completes these actions in the production environment, but you can use these methods to complete a test case in the sandbox.

In the Resolution Center, the customer selects Report a Problem and then selects the type of dispute from these options:

I didn't receive an item purchased
I received an item that wasn't as described
I want to report unauthorized activity
I have a billing issue

Then, a dispute is created, and the Resolution Center prompts the customer to contact the seller about the problem.

Disputes API and Resolution Center

These actions provided by the Disputes API methods are also available in the Resolution Center where you can update your claim manually. The following table shows the methods available as actions in the Resolution Center.

Method	Resolution Center Actions
List disputes	Go to Case summary. Select Open Cases.
Show dispute details	Under Case ID, click the plus sign to show the transaction ID, date opened, and other details.
Send message to other party	On the case summary page, click View. Select Message, enter the message details, and click Send.
Make offer to resolve dispute	On the case summary page, click View. Select Make an offer. Select which offer to make: Full refund offer with item return, Partial refund offer, Replacement offer.
Escalate dispute to a claim	On the Escalate to Paypal page, enter the detailed description, and select Send.
Provide evidence	Click Enter tracking information and order status. Enter the information and click Submit. You can provide more evidence by uploading files.
Accept claim	To accept the claim, select I'll issue a refund to my customer and close this case.
Appeal dispute	To appeal the dispute, select I disagree with the claim. I'd like to submit additional info.

Dispute use cases

Some common use cases for the Disputes API include:

A merchant with a high volume of disputes must automate their handling.
A merchant wants to manage PayPal disputes from the merchant's own dispute management tool used by its customer service agents instead of the PayPal resolution center.
A shopping cart wants to show open disputes with PayPal to merchants, but does not provide management of the disputes.
A platform provides management of PayPal disputes to its merchants through its own administration interface so that they can manage disputes in one place.

Dispute lifecycle stages

To understand the dispute management flow, learn about the dispute lifecycle stages:

Inquiry stage
Claim stage
Settlement stage

Inquiry stage

The inquiry stage occurs immediately after a customer initiates a dispute by reporting a problem in the Resolution Center. The customer and merchant attempt to resolve the dispute for a 20-day period without escalation to PayPal.

The dispute_lifecycle_stage is INQUIRY.

Claim stage

If the customer and merchant cannot resolve the dispute within the 20-day inquiry period, the customer or merchant can escalate the dispute to PayPal. The dispute then enters the claim stage.

The dispute_lifecycle_stage is one of these values:

CHARGEBACK. A customer or merchant escalates an inquiry to a claim, which authorizes PayPal to investigate the case and make a determination. Occurs only when the dispute channel is INTERNAL.

After the dispute enters this phase, all notes that the customer sends are visible to PayPal agents only. The customer must wait for PayPal’s response before he or she can take further action. PayPal shares dispute details with the merchant, who can accept the customer's claim, submit evidence to challenge the customer's claim, or make an offer to resolve the dispute.

Note: The chargeback stage is a PayPal dispute lifecycle stage and is not a credit card or debit card chargeback.
PRE_ARBITRATION. The first appeal stage for merchants. A merchant can appeal a chargeback if a decision is not in the merchant's favor. If the merchant does not appeal within the appeal period, the case is considered resolved.
ARBITRATION. The second appeal stage for merchants. Available if the first appeal is denied. A merchant can appeal a dispute for a second time if the first appeal was denied. If the merchant does not appeal within the appeal period, the case returns to a resolved status in pre-arbitration stage.

Settlement stage

To resolve the claim, PayPal considers the submitted evidence and settles the dispute in either the customer's or merchant's favor and communicates the outcome of the dispute to the bank, if involved, and the merchant and customer.

The dispute_lifecycle_stage is one of these values: INQUIRY, CHARGEBACK, PRE_ARBITRATION, or ARBITRATION.

Dispute management flow

PayPal Disputes settlement stage

The customer and merchant resolve a dispute without escalation to PayPal.
The customer initiates a dispute with PayPal.
PayPal uses a webhook or calls show dispute details to share dispute details with the merchant.
The merchant provides evidence or appeals the dispute to show that the charge is legitimate. The evidence that the merchant submits can be a proof of delivery document, a proof of refund document, or notes, which can include logs.
PayPal settles the dispute in the customer's or merchant's favor and PayPal communicates the outcome to the merchant and customer, and the bank, if involved.

Dispute methods

The Disputes API methods that you can call depend on the dispute status and the stage in the dispute lifecycle:

Method	Dispute status and lifecycle stage
List disputes	`OPEN` `UNDER_REVIEW` `RESOLVED` `OTHER`
Show dispute details	`OPEN` `UNDER_REVIEW` `RESOLVED` `OTHER`
Acknowledge returned item	`OPEN` `UNDER_REVIEW` `RESOLVED` `OTHER`
Send message to other party	`INQUIRY`
Make offer to resolve dispute	`INQUIRY`
Escalate dispute to a claim	`INQUIRY`
Provide evidence	`WAITING_FOR_BUYER_RESPONSE` `WAITING_FOR_SELLER_RESPONSE`
Accept claim	Not tied to any status
Appeal dispute	`RESOLVED` in the customer's favor
Update dispute status	`UNDER_REVIEW`
Settle dispute	`UNDER_REVIEW`

Continue to the Disputes Integration Guide.