Disputes REST API

Disputes Overview


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

Tip: Try the Disputes demo.

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 escalate a dispute to a claim and update the dispute status. 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 use case flows

The buyer can file a dispute directly with the merchant or on PayPal's Resolution Center. If the dispute is settled in the buyer's favor, a refund is initiated to the buyer. Disputes Flow Marketplace

The buyer can file a dispute with the bank or card issuer. If the dispute is settled in the buyer's favor, a refund is initiated to the buyer. Disputes Flow Bank

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
  1. Go to Case summary.
  2. 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
  1. On the case summary page, click View.
  2. Select Message, enter the message details, and click Send.
Make offer to resolve a dispute
  1. On the case summary page, click View.
  2. Select Make an offer.
  3. 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
  1. Click Enter tracking information and order status.
  2. 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

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. 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

A dispute can be resolved in the inquiry stage or the claim stage. When a dispute is resolved, it enters the settlement stage.

Dispute management flow

Available actions by stage

The actions that are available to the seller and buyer vary during the stages of a dispute. The following table shows the actions that are available to the buyer and seller during the stages of a dispute. Refer to the HATEOAS links to determine actions available for the dispute.

Important: These actions are available only in the sandbox: settle dispute, create dispute, and update dispute status.

Stage Seller actions Buyer actions
Gathering information
Inquiry
Claim

Next

Continue to the Disputes Integration Guide.

Additional information