Customer Disputes

Important: PayPal Customer Disputes API is a limited-release solution at this time. It is available to select partners for approved use cases. For more information, reach out to your PayPal account manager or contact us.

PayPal merchants, partners, and external developers can use the PayPal Customer Disputes API to list disputes, show dispute details, provide evidence, accept claims, and appeal disputes. This API is a limited release REST API that you can use in conjunction with other publicly available external APIs.

Overview

Occasionally, something goes wrong with a buyer's order. To dispute a charge, a buyer can file a case with PayPal or ask his or her bank or credit card company to reverse a charge. A charge reversal is also known as a chargeback. For more information, see Disputes, claims, chargebacks, and bank reversals.

When a buyer disputes your charge, you can provide evidence to show that the charge is legitimate. To provide new evidence or appeal a dispute, you submit a proof of delivery or proof of refund document or notes, which can include logs.

Prerequisites

To use the Customer Disputes API, you must:

1. Be a merchant or a partner in the PayPal Partner Program.

2. Create a PayPal app and get an access token. When you create a PayPal app, PayPal generates a set of OAuth client_id and secret keys for the application. PayPal generates these keys for both the sandbox and live environments. To get an access token, pass the client-id:secret credentials in the Authorization header. You use the access token for authentication when you make REST API requests.

   Learn how to make your first call and about HTTP request headers. If you are a non-US developer, see International Developer Questions.

Use cases

Review these use cases to learn how to use the Customer Disputes API:

• Buyer appeals dispute
• Seller appeals dispute
• Seller accepts claim
• Marketplace lists disputes

Buyer appeals dispute

In this scenario, a buyer purchases an item that she never receives. She reports the issue to the merchant, who creates a case for the buyer in the PayPal Resolution Center. The case is initially denied. To appeal the dispute, she provides additional evidence. This time, the dispute is closed in her favor.

Seller appeals dispute

In this scenario, a buyer purchases a red shirt but receives a blue shirt. She creates a dispute that the seller does not respond within the prescribed service level agreement (SLA) so the dispute is closed in the buyer's favor. Then, the seller provides evidence to challenge the closed dispute. In response to a request, the buyer provides additional evidence to support her dispute. Again, her dispute is closed in her favor.

Seller accepts claim

In this scenario, a buyer uses her PayPal account to buy an item from a seller. An internal error causes her account to be overcharged so she creates a dispute, which the seller accepts. The seller posts a refund to her PayPal account.

Marketplace lists disputes

In this scenario, the buyer uses her PayPal account to buy an item from a marketplace. Because she has an issue with the transaction, she creates a case with PayPal. The marketplace wants to monitor disputes against the seller. For information, see Marketplace lists disputes.

Create dispute

Merchants can create cases for buyers in the PayPal Resolution Center. This method is not yet available. However, when it is available, the method is intended only for creating disputes in the sandbox for integration testing.

List disputes

Sellers can list buyer disputes.

To filter the disputes in the response, you can specify one or more optional query parameters. You can specify the page_size query parameter to limit the number of disputes in the response.

When you list disputes, the response shows the dispute_id, reason, status, dispute_amount, create_time, and update_time fields for each dispute.

For information, see list disputes in the API reference.

Provide evidence

Buyers and sellers can provide evidence for a dispute, by ID. sellers can provide evidence for disputes that have the WAITING_FOR_SELLER_RESPONSE status while buyers can provide evidence for disputes that have the WAITING_FOR_BUYER_RESPONSE status.

Evidence can be a proof of delivery or proof of refund document or notes, which can include logs. A proof of delivery document includes a tracking number while a proof of refund document includes a refund ID.

The following rules apply to document file types and sizes:

• The seller can upload up to 10 MB of files for a case.
• Individual files must be smaller than 5 MB.
• The supported file formats are JPG, GIF, PNG, and PDF.

To make this request, specify the dispute ID in the URI and specify the evidence in the JSON request body.

The response provides a HATEOAS links that enables you to get more information about the dispute.

For information, see provide evidence in the API reference.

Accept claim

When you accept a claim for a dispute, the dispute closes in the buyer's favor and you refund the buyer's money from your seller's account.

In addition to specifying the ID of the dispute in the URI, specify one or more optional parameters in the JSON request body:

• Your notes for acceptance of the buyer's claim.
• Your reason for acceptance of the buyer's claim.
• The ID of the invoice for the refund.

For information, see accept claim in the API reference.

Show dispute details

To show details for a dispute, you include the dispute ID in the request URI. The response shows dispute details and HATEOAS links that enable you to complete other actions for the dispute.

Note: The fields that appear in the response depend on whether you access this call through first- or third-party access. For example, if the seller shows dispute details through third-party access, the buyer's email ID does not appear.

For information, see show dispute details in the API reference.

Appeal dispute

You can appeal a lost dispute, by ID. To appeal a dispute, use the appeal link in the HATEOAS links from the show dispute details response. If this link does not appear, you cannot appeal the dispute.

Specify the dispute ID in the URI. Include evidence in the JSON request body.

Evidence can be a proof of delivery or proof of refund document or notes, which can include logs. A proof of delivery document includes a tracking number while a proof of refund document includes a refund ID.

The following rules apply to document file types and sizes:

• The seller can upload up to 10 MB of files for a case.
• Individual files must be smaller than 5 MB.
• The supported file formats are JPG, GIF, PNG, and PDF.

For information, see appeal dispute in the API reference.

Additional information

• Customer Disputes API reference
• Disputes, claims, chargebacks, and bank reversals
• Marketplace Disputes Integration Guide
• HATEOAS links