Customer Disputes Integration Guide

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.

For more information about customer disputes:

Topic See
Frequently asked questions (FAQ) Customer FAQs
Webhooks for notification with Customer Disputes Customer Disputes and Webhooks
Test your integration Customer Disputes and Integration Testing

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

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.

Buyer

  1. The buyer uses her PayPal account to buy an item from the seller but she never receives the item.

  2. She reports the issue to the merchant, who creates creates a dispute to file an MERCHANDISE_OR_SERVICE_NOT_RECEIVED case for her in the PayPal Resolution Center.
Seller

  1. The seller is notified about the dispute. To review the dispute, he shows dispute details.

  2. He provides evidence as a shipment tracking number.

  3. PayPal customer support reviews and closes the dispute in the seller's favor.
Buyer

  1. The buyer appeals the dispute and provides evidence as additional notes.

  2. PayPal customer support reviews and closes the dispute in the buyer's 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.

Buyer

  1. The buyer uses her PayPal account to buy a red shirt from the seller but receives a blue shirt.

  2. She creates a dispute to file an MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED case.
Seller

  1. The seller is notified about the dispute. To review the dispute, he shows dispute details.

    However, because he fails to respond to the dispute within the prescribed SLA, PayPal customer support closes the dispute in the buyer's favor.

  2. To challenge the closed dispute, the seller appeals the dispute and provides evidence as order details.
Buyer

  1. PayPal customer support reviews the dispute and requests additional information from the buyer.

  2. The buyer provides additional evidence.

  3. PayPal customer support closes the dispute in the buyer's 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.

Buyer

  1. The buyer uses her PayPal account to buy a $40.00 item from the seller. However, an internal error causes her account to be overcharged by $4.00.

  2. She creates a dispute to file an INCORRECT_AMOUNT case.
Seller

  1. The seller is notified about the dispute. To review the dispute, he shows dispute details.

  2. He accepts the claim and refunds $4.00 to the buyer's PayPal account. This action closes the dispute.

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. For information about dispute reason codes that are associated with evidence types, see dispute reason codes.

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. See dispute reason codes.
  • 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.

Dispute reason codes

These dispute reasons require this information for these evidence types:

Dispute reason and description Evidence type Required
MERCHANDISE_OR_SERVICE_NOT_RECEIVED
The customer did not receive the merchandise or service.		 PROOF_OF_FULFILLMENT
  • tracking_number
  • carrier_name
PROOF_OF_REFUND refund_ids
OTHER A note or document1. For example, a document can be a proof of delivery signature or a proof of receipt copy.
MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED
The customer reports that the merchandise or service was not as described.		 OTHER A note or document1. For example, a document can be a description, item URL, return policy, or a copy of a contract or an affidavit.
PROOF_OF_REFUND A set of refund_ids.
UNAUTHORISED
The customer did not authorize purchase of the merchandise or service.		 PROOF_OF_FULFILLMENT
  • tracking_number
  • carrier_name
PROOF_OF_REFUND The refund ID.
OTHER A note or document1. For example, a document can be a proof of delivery signature or a proof of receipt copy.
CREDIT_NOT_PROCESSED
The credit transaction was not processed for the customer.		 PROOF_OF_REFUND The refund ID.
OTHER A note or document1. For example, a document can be a credit due reason.
DUPLICATE_TRANSACTION
The transaction was a duplicate.		 PROOF_OF_FULFILLMENT The tracking_number, carrier_name, and duplicate or multiple orders.
PROOF_OF_REFUND The refund ID.
OTHER A note or document1
INCORRECT_AMOUNT
The customer was charged an incorrect amount.		 PROOF_OF_REFUND The refund ID, for the difference in amount.
OTHER A note or document1. For example, a document can be a price difference reason.
PAYMENT_BY_OTHER_MEANS
The customer paid for the transaction through other means.		 PROOF_OF_REFUND The refund ID, for the difference in amount.
OTHER A note or document1.
CANCELED_RECURRING_BILLING
The customer was incorrectly charged because he or she canceled recurring billing.		 PROOF_OF_REFUND The refund ID, for the difference in amount.
OTHER A note or document1. For example, a document can be a subscription agreement.
OTHER
 PROOF_OF_SHIPMENT
  • tracking_number
  • carrier_name
PROOF_OF_REFUND The refund ID.
OTHER A note or document1.

1The seller can upload up to 10 MB of files for a case:

  1. Individual files must be smaller than 5 MB.
  2. The supported file formats are JPG, GIF, PNG, and PDF.
  3. To make this request, specify the dispute ID in the URI and specify the evidence in the JSON request body.
  4. The length of the text for notes cannot be more than 2000 characters.

Additional information