Marketplace Disputes Integration Guide

Important: PayPal for Marketplaces 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 customer's order. To dispute a charge, a customer 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 customer 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 merchant 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 merchants 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 merchants manage their own disputes through PayPal’s Resolution Center. When your merchants 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 merchant agrees to during onboarding.

To receive information on merchants’ 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. Merchants who resolve disputes can use this API as a pull mechanism to show details for the dispute.

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

PayPal communicates directly with the merchant when disputes occur.

Actively manage disputes

You can manage disputes on behalf of your merchants. To do so, you must obtain your merchants’ 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 merchants 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 merchants 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 merchants 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 Disputes API:

Marketplace lists disputes

In this scenario, the customer 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 merchant.

Customer
  1. The customer 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.

Merchant
  1. The merchant is notified of the dispute. The merchant 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.

Customer
  1. The customer 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 customer files an Item Not Received case with PayPal. The marketplace shows the dispute details and responds to the case with tracking information.

Customer
  1. The customer 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 merchant 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 customer in her PayPal account.

Customer
  1. The customer 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 customer's favor.

  3. To challenge the closed dispute, the marketplace appeals the dispute and provides evidence as order details.

Customer
  1. PayPal Customer Support reviews the dispute and requests additional information from the buyer.

  2. The customer 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 customer purchases a red shirt but receives a blue shirt. She creates a dispute but the merchant does not respond within the prescribed service level agreement (SLA), so the dispute is closed in the customer's favor. Then, the merchant provides evidence to challenge the closed dispute. In response to a request, the customer provides additional evidence to support her dispute. Again, her dispute is closed in her favor.

Customer
  1. The customer uses her PayPal account to buy a red shirt from the merchant 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, the marketplace 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 customer's favor.

  3. To challenge the closed dispute, the marketplace appeals the dispute and provides evidence as order details.

Customer
  1. PayPal Customer Support reviews the dispute and requests additional information from the customer.

  2. The customer 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 customer 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

Merchants can list customer 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.

Provide evidence

Merchants and customers can provide evidence for a dispute, by ID. Merchants 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 merchant 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 customer's favor and you refund the customer's money from your merchant account.

Specify the ID of the dispute in the URI and specify one or more optional parameters in the JSON request body:

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

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 merchant shows dispute details through third-party access, the customer's email ID does not appear.

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 can't 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 merchant 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