Customer Disputes Overview

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

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 or ask his or her 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 Customer Disputes API to 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 create a dispute, update the dispute status, and settle a dispute. 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.

Dispute use cases

Some common use cases for the Customer 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
• Claim stage
• Settlement stage

Inquiry stage

The customer and merchant resolve the dispute without escalation to PayPal.

The dispute_lifecycle_stage is INQUIRY.

Claim stage

If the customer and merchant cannot resolve the dispute, the customer initiates a dispute with PayPal and the dispute 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. Available if the first appeal is denied. 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 any value.

Dispute management flow

Dispute methods

The Customer Disputes API methods that you can call depend on the dispute status and the stage in the dispute lifecycle:

Next

Continue to the Customer Disputes Integration Guide.

Additional information

• Customer Disputes Frequently Asked Questions (FAQ)
• Disputes, claims, chargebacks, and bank reversals
• Customer Disputes API reference