Marketplace Disputes Integration Guide

Important: PayPal for Marketplaces 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.

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 charge back. For more information, see Disputes, claims, charge backs, 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.

Connected path solutions

We work with the seller to investigate the dispute and make a final decision regarding the case. You decide how involved you want to be in dispute management. You can choose to be informed about the disputes while letting your sellers manage their own disputes, or you can own the active dispute management on behalf of your sellers.

Note: Most Connected path partners choose not to actively manage disputes, but rather play an informed role.

Stay informed about disputes

If you prefer, you can choose to let your sellers manage their own disputes through PayPal’s Resolution Center. When your sellers manage their own disputes, you still have the option to stay informed about the disputes that are occurring within your platform.

Set up dispute notifications

You can enable dispute notifications in one simple step. To receive dispute notifications, add the Disputes permission text to the permissions that your seller agrees to during onboarding.

To receive information on sellers’ disputes, use one of these methods:

  • Marketplace Case Reconciliation Report. PayPal can generate a report with cases that opened or closed within the reporting time frame.

  • Dispute webhooks. PayPal sends you an update through webhook notification messages when a dispute is created, updated, or resolved.

  • Disputes API. Sellers who resolve disputes can use this API as a pull mechanism to show details for the dispute.

The seller is responsible for responding to disputes in a timely manner in PayPal’s Resolution Center.

PayPal communicates directly with the seller when disputes occur.

Actively manage disputes

You can manage disputes on behalf of your sellers. To do so, you must obtain your sellers’ permission during the onboarding process. Add the Active Dispute Management permission text to your onboarding permissions.

As the manager of the dispute process, you:

  • Receive dispute notification messages and case details from PayPal.

    • PayPal sends webhook notification messages when a dispute is created, updated or resolved.

    • You can also invoke the pull mechanism of the Disputes API to get more details about disputes.

  • Must respond to disputes in a timely manner with relevant information.

    • When you receive a dispute, it is your responsibility to respond to the case with relevant information. You might need to reach out to your sellers in some cases for evidence.

    • You respond to the case with relevant information when you provide evidence for a dispute or accept a claim.

Managed path solutions

You manage the disputes process on behalf of your sellers and are responsible for responding to disputes in a timely manner.

What you must do

As the manager of the dispute process, you:

  • Receive dispute notification messages and case details from PayPal.

    • PayPal sends webhook notification messages when a dispute is created, updated, or resolved.

    • PayPal can generate a Marketplace Case Reconciliation Report with cases that opened or closed within the reporting time frame.

    • You can also invoke the pull mechanism of the Dispute API to get more details about the disputes.

  • Must respond to disputes in a timely manner with relevant information.

    • When you receive a dispute, it is your responsibility to respond to the case with relevant information. You might need to reach out to your sellers in some cases for evidence.

    • You respond to the case with relevant information when you provide evidence for a claim or accept a claim.

Use cases

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

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.

Buyer
  1. The buyer uses her PayPal account to buy an item from an online marketplace.

  2. Because she has an issue with the transaction, she creates a case in PayPal.

Seller
  1. The seller is notified of the dispute. The seller manages the dispute on PayPal’s Resolution center.

    Note: For the Managed path, the marketplace is responsible for managing the disputes.
Marketplace
  1. The marketplace is notified of the dispute through a webhook notification message.

  2. The marketplace uses the merchant ID to list disputes.

Marketplace shows dispute details

In this scenario, the marketplace must show detailed information about the dispute so that it can respond to it.

Buyer
  1. The buyer uses her PayPal account to buy an item from an online marketplace.

  2. Because she has an issue with the transaction, she creates a case in PayPal.

Marketplace
  1. The marketplace is notified of the dispute through a webhook.

  2. The marketplace uses the dispute ID to show dispute details.

Marketplace provides evidence

In this scenario, the buyer files an Item Not Received case with PayPal. The marketplace shows the dispute details and responds to the case with tracking information.

Buyer
  1. The buyer uses her PayPal account to buy an item from an online marketplace.

  2. Because she has an issue with the transaction, she creates a case in PayPal.

Marketplace
  1. The marketplace is notified of the dispute through a webhook notification message.

  2. The marketplace uses the dispute ID to show dispute details.

  3. To send the PayPal tracking information, the marketplace provides evidence.

    Note: A Connected marketplace can choose to let the seller manage disputes.

Marketplace accepts claim

In this scenario, the marketplace decides to accept the case as the buyer is a valuable and loyal customer. This results in a refund to the buyer in her PayPal account.

Buyer
  1. The buyer uses her PayPal account to buy an item from an online marketplace.

  2. Because she has an issue with the transaction, she creates a case with PayPal.

Marketplace
  1. The marketplace is notified of the dispute through a webhook notification message.

  2. The marketplace does not respond to the dispute within the prescribed service level agreement (SLA) so PayPal customer support closes the dispute in the buyer’s favor.

  3. To challenge the closed dispute, the marketplace 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 reviews the evidence provided by both parties and decides the case.

Marketplace 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 a MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED case.

Marketplace
  1. The marketplace is notified about the dispute through a webhook notification message. To review the dispute, he shows dispute details.

  2. The marketplace does not respond to the dispute within the prescribed time period in the service level agreement (SLA) so PayPal customer support closes the dispute in the buyer’s favor.

  3. To challenge the closed dispute, the marketplace 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 reviews the evidence provided by both parties and decides the case.

Prerequisites

Before you can use the Disputes API, you must:

Note: This integration guide assumes that the buyer has already opened a dispute with PayPal.

Integration steps

Here’s how to integrate dispute management through the Disputes API:

1. Required List disputes.
2. Required Provide evidence.
3. Required Accept a claim.
4. Optional Show dispute details.
5. Optional Appeal a dispute.

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

Sellers and buyers 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 link 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 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, 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 show dispute details 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.

Congratulations

You’ve set up dispute management.

Next: Go to the Reporting Setup Guide to set up reports for your platform.

Additional information