Customer Disputes Integration Guide

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

For concepts, see the Customer Disputes Overview.

Integration steps

Step Required Stage Description
1. Required Prerequisite Enable the Customer Dispute API.
2. Required Prerequisite Get access token.
3. Optional Prerequisite To make calls on behalf of a third party, you must be a partner in the PayPal Partner Program.
4. Optional Gather dispute information You can list disputes, show details for a single dispute, and acknowledge returned items.
5. Optional Inquiry You can send message to the other party, make an offer to resolve the dispute, and escalate a dispute to a claim.
6. Optional Claim You can provide evidence, accept the claim, or appeal the dispute if it was resolved in favor of the counter party.
7. Optional Settlement In the sandbox, you can create a dispute, update the dispute status, and settle the dispute. See Customer Disputes and Integration Testing.

Get access token

To make REST API calls, create a PayPal REST app and get an access token:

1. Create a PayPal app.

When you create an app, PayPal generates a set of OAuth credentials.
2. Get an access token.

Pass the OAuth credentials in a get access token call.

In exchange for these credentials, the PayPal authorization server issues a bearer token, which is a type of access token that you use for authorization when you make REST API requests against protected resources on either your own or a third party's behalf.

For information about third-party access, contact your PayPal account manager.

Gather dispute information

You can gather dispute information during any dispute lifecycle stage. To gather information, you can list disputes, show details for a single dispute, and acknowledge receipt of a returned item.

List disputes

Merchants can list customer disputes.

To filter the disputes in the response, you can specify one or more optional query parameters:

Parameter Type Description
start_time string Filters the disputes in the response by a creation date and time. The start time must be within the last 180 days. Value is in Internet date and time format. For example, yyyy-MM-ddTHH:mm:ss.SSSZ.

You can specify either but not both the start_time and disputed_transaction_id query parameter. If you omit the start time, default is the current date and time.
disputed_transaction_id string Filters the disputes in the response by a transaction, by ID.

You can specify either but not both the start_time and disputed_transaction_id query parameter.
page_size integer Limits the number of disputes in the response to this value. Default is 10, minimum value is 1, and maximum value is 50.
next_page_token string The token that describes the next page of results to fetch. The list disputes call returns this token in the HATEOAS links in the response. If you omit this parameter, the API returns the first page of data.
dispute_state string Filters the disputes in the response by a state.

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.

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

For information, see show dispute details in the API reference.

Acknowledge returned item

At any stage in the dispute lifecycle, merchants can request that the customer return a MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED item or service for a full refund. Until the merchant calls provide evidence to provide PROOF_OF_RETURN, the dispute has the WAITING_FOR_SELLER_RESPONSE status.

For information, see acknowledge returned item in the API reference.

Inquiry stage

In the inquiry stage, the dispute status must be INQUIRY.

In this stage, you can send a message to the other party, make an offer to resolve the dispute, and escalate a dispute to a claim.

Currently, you can escalate a dispute to a claim in the sandbox only.

Send message to other party

To send a message to the other party, you include the dispute ID in the request URI.

You must also include a message to the other party in the JSON request body.

A successful request returns the HTTP 200 OK status code and a JSON response body that includes a link to the dispute.

Make offer to resolve dispute

A merchant can make these types of offers to a customer:

Offer type Description
Refund only The merchant agrees to refund a specific amount to the customer.
Refund with return from customer The merchant agrees to refund the full dispute amount but expects the customer to return the item to a specific return address.
Refund with replacement to customer The merchant agrees to refund a specific amount and agrees to send the customer a replacement item.
Replacement without refund The merchant agrees to send a replacement item, but issues no refund.

To make an offer to resolve a dispute, you include the dispute ID in the request URI.

You must also include a note about the offer and the offer amount. You can optionally include a return shipping address for the item and the ID of the invoice for the refund:

note string Required The notes about the offer.
offer_amount object Required The amount proposed to resolve the dispute.
return_shipping_address object Optional The return address for the item.
invoice_id string Optional The ID of the invoice for the refund.

A successful request returns the HTTP 200 OK status code and a JSON response body that includes a link to the dispute.

Escalate dispute to claim

You can escalate a dispute, by ID, to a PayPal claim to resolve the dispute.

You specify the dispute ID in the URI and include a note about the escalation in the JSON request body:

https://api.sandbox.paypal.com/v1/customer/disputes/PP-000-000-651-454/escalate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token" \
  -d '{
  "note": "Escalating to PayPal claim for resolution."
}'

A successful request returns the HTTP 200 OK status code and a JSON response body that includes a link to the dispute:

{
  "links": [{
    "rel": "self",
    "method": "GET",
    "href": "https://api.sandbox.paypal.com/v1/customer/disputes/PP-000-000-651-454"
  }]
}

Claim stage

In the claim stage, you can provide evidence, accept a claim, and appeal a dispute.

Provide evidence

Customers and merchants can provide evidence for a dispute, by ID. Merchants can provide evidence for disputes that have the WAITING_FOR_MERCHANT_RESPONSE status while customers 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.

Each dispute reason requires certain information for various evidence types. See dispute reasons.

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.
  • The maximum length of notes is 2000 characters.

To make this request, specify the dispute ID in the URI and specify the evidence in the JSON request body. For information about dispute reasons that are associated with evidence types, see dispute reasons.

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 customer's favor and you refund the customer's money from your merchant'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 customer's claim.
  • Your reason for acceptance of the customer's claim. See dispute reasons.
  • The ID of the invoice for the refund.

For information, see accept claim 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, and submit new evidence as a document or notes 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 about dispute reasons, see dispute reasons.

For information, see appeal dispute in the API reference.

Sandbox-only methods

An agent at PayPal normally completes specific dispute-related actions in the production environment. However, you can complete these tests in the sandbox:

To test your integration with the Customer Disputes API, see Customer Disputes and Integration Testing.

Dispute reasons

Each dispute reason requires certain information for various evidence types:

MERCHANDISE_OR_SERVICE_NOT_RECEIVED

The customer did not receive the merchandise or service.

Evidence type Required
PROOF_OF_FULFILLMENT
  • tracking_number
  • carrier_name
PROOF_OF_REFUND

refund_ids

OTHER

A note or document. 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.

Evidence type Required
OTHER

A note or document. 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.

Evidence type Required
PROOF_OF_FULFILLMENT
  • tracking_number
  • carrier_name
PROOF_OF_REFUND

The refund ID.

OTHER

A note or document. 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.

Evidence type Required
PROOF_OF_REFUND

The refund ID.

OTHER

A note or document. For example, a document can be a credit due reason.

DUPLICATE_TRANSACTION

The transaction was a duplicate.

Evidence type Required
PROOF_OF_FULFILLMENT

The tracking_number, carrier_name, and duplicate or multiple orders.

PROOF_OF_REFUND

The refund ID.

OTHER

A note or document.

INCORRECT_AMOUNT

The customer was charged an incorrect amount.

Evidence type Required
PROOF_OF_REFUND

The refund ID, for the difference in amount.

OTHER

A note or document. For example, a document can be a price difference reason.

PAYMENT_BY_OTHER_MEANS

The customer paid for the transaction through other means.

Evidence type Required
PROOF_OF_REFUND

The refund ID, for the difference in amount.

OTHER

A note or document.

CANCELED_RECURRING_BILLING

The customer was incorrectly charged because he or she canceled recurring billing.

Evidence type Required
PROOF_OF_REFUND

The refund ID, for the difference in amount.

OTHER

A note or document. For example, a document can be a subscription agreement.

OTHER

Evidence type Required
PROOF_OF_SHIPMENT
  • tracking_number
  • carrier_name
PROOF_OF_REFUND

The refund ID.

OTHER

A note or document.

Documents

The merchant 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

Feedback