Integrate Dispute APIs
Last updated: Dec 17th, 6:52am
PayPal merchants, partners, and external developers can use the PayPal Disputes API to manage disputes. For concepts, see Manage disputes and chargebacks.
Integration steps
Step | Required | Stage | Description |
---|---|---|---|
1. | Required | Prerequisite | Set up your development environment. |
2. | Optional | Gather dispute information | You can list disputes and show details for a single dispute. |
3. | Optional | Respond to a dispute | You can respond to a dispute once you have gathered information about the dispute. |
4. | Optional | Get started with sandbox | You can use sandbox to test out the dispute flows. |
Set up your development environment
Before you can integrate Disputes, set up your development environment. After you get a token that lets you access protected REST API resources, create sandbox accounts to test your web and mobile apps.
When you create an app, enable Disputes in the App feature options section. For details, see Get Started.
Then, return to this page to integrate Disputes.
PayPal-Auth-Assertion request header
Ensure you include the PayPal-Auth-Assertion request header when using an access token to make third party API calls on behalf of another merchant.
It is an API client-provided JSON Web Token (JWT) assertion that identifies the merchant. To use this header, you must get consent to act on behalf of a merchant. For more details, see HTTP request headers.
Gather dispute information
To gather information about a dispute, you can show dispute details for a single dispute or you can list disputes to see all the disputes associated with an account.
List disputes
Merchants and partners can list the disputes related to an account using the list disputes API. The response shows you some basic information about the dispute. You can filter the results based on query parameters when you list disputes. For example, you can use the disputed_transaction_id parameter
to filter the results only to show disputes related to a particular transaction
- Request
- Response
1curl -v -X GET https://api-m.sandbox.paypal.com/v1/customer/disputes/ \23-H 'Content-Type: application/json' \45-H 'Authorization: Bearer ACCESS_TOKEN'
A successful request returns the HTTP 200 OK status code and a JSON body that includes the list of disputes.
For a full list of query parameters and detailed information about response structure, see list disputes in the API reference.
Show dispute details
Merchants can use the show dispute details API to retrieve details about a dispute to retrieve details about a dispute. The dispute details response contains HATEOAS links listing all the applicable actions merchants can complete on the dispute. At any given point in the dispute lifecycle, the merchant can refer to the HATEOAS links provided in the dispute details response to identify various ways in which they can respond to the dispute.
You specify the dispute ID in the URI to fetch details about a single dispute.
- Request
- Response
1curl -v -X GET https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-4012 \23-H 'Content-Type: application/json' \45-H 'Authorization: Bearer ACCESS_TOKEN
A successful request returns the HTTP 200 OK status code, and a JSON body that includes the details about the dispute queried.
Note: The fields 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 show up.
For additional information, see show dispute details in the API reference.
Respond to a dispute
Merchants and partners can use the information from the gathering information step to appropriately respond to a dispute. They can refer to the HATEOAS links returned as part of the dispute details API to understand which respond options are available to the merchant at any given point of time during the dispute case lifecycle.
The ways you can respond to a dispute depends upon various factors. One such important factor is the lifecycle stage of the dispute which you get as the value for the dispute_life_cycle_stage
attribute of the dispute details API response.
Inquiry stage
The inquiry stage occurs immediately after a customer initiates a dispute by reporting a problem in the Resolution Center. It intends to let the buyer and merchant resolve the dispute amicably without PayPal's involvement.
In scenarios where the two parties cannot resolve the issue, and the case is escalated to PayPal, it moves to the claim stage.
During the inquiry stage, a merchant can respond to the dispute in multiple ways. They can send messages to the other party, make offers to the other party, or provide tracking details as proof of fulfillment, to name a few.
Claim stage
If the customer and merchant cannot resolve the dispute within the inquiry period, the customer or merchant can escalate the dispute to PayPal.
The dispute then enters the claim stage. Note that this is true only for internal PayPal disputes. Regarding external chargebacks, the respective financial institutions handle the adjudication. In the claim stage, the merchant can respond by providing evidence or they can accept the claim.
Merchants can also appeal cases that don't go in their favor. To know whether they can appeal a case, merchants can refer to the HATEOAS links returned as part of the dispute details response.
Send a message to the other party
To send a message to the other party, include the dispute ID in the request URI and add the message content in the JSON request body.
Note: Merchants can also attach documents and pictures to the message. To do so, they must send a multipart request instead of a JSON one.
A successful request returns the HTTP 200 OK status code and a JSON response body with a dispute link.
- Request
- Multipart Request
- Response
1curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-000-000-651-454/send-message \2-H 'Content-Type: application/json' \3-H 'Authorization: Bearer ACCESS_TOKEN' \4-d '{5 "message": "Shipment is in progress."6}'
For additional information, see send message in the API reference.
Make an offer to resolve a dispute
The merchant can make an offer to the buyer to resolve the dispute. To know which offers are applicable for a particular dispute, refer to the allowed response options for makeoffer in the dispute details API response.
Review the description for each offer type to determine the information the merchant should send with the request for that type.
- Request
- Response
1curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-000-000-651-454/make-offer \2-H 'Content-Type: application/json' \3-H 'Authorization: Bearer ACCESS_TOKEN' \4-d '{5 "note": "Offer refund with replacement item.",6 "offer_amount": {7 "currency_code": "USD",8 "value": "23"9 },10 "offer_type": "REFUND_WITH_REPLACEMENT"11}'
A successful request returns the HTTP 200 OK status code and a JSON response body with a dispute link.
Accept claim
The merchant can accept liability for a dispute using the accept claim API. When a merchant accepts a claim, the dispute closes in the buyer's favor, and PayPal automatically refunds money to the buyer from the merchant's account.
In addition to specifying the ID of the dispute in the URI, the merchant can specify one or more optional parameters in the JSON request body:
`note`
- Notes for acceptance of the customer's claim.`accept_claim_reason`
- Reason for acceptance of the customer's claim. For more information, see accept claim reasons.`invoice_id`
- The ID of the invoice for the refund.
- Request
- Response
1curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803/accept-claim \2-H 'Content-Type: application/json' \3-H 'Authorization: Bearer ACCESS_TOKEN' \4-d '{5 "note": "Full refund to the customer."6}'
A successful request returns the HTTP 200 OK status code and a JSON response body that includes a link to the dispute.
For additional information, see accept claim in the API reference.
Provide evidence
Buyers and merchants can provide evidence for a dispute. Merchants can provide evidence for disputes with the `WAITING_FOR_SELLER_RESPONSE`
status, while buyers can provide evidence for disputes with the `WAITING_FOR_BUYER_RESPONSE`
status.
The evidence should be relevant to the reason for the dispute. To determine the type of evidence requested, merchants can refer to the evidence array returned as part of the dispute details API response. They can look at the evidence type of the evidence objects with the source labeled as `REQUESTED_FROM_SELLER`
.
Depending on the `evidence_type`
, the merchant might also need to provide additional information like `refund_ids`
or `tracking_info`
as part of the evidence info object. They can also add any relevant `notes`
or `documents`
to the request.
- The maximum length of notes can be 2000 characters.
- For constraints and rules regarding documents, see documents.
To make this request, specify the dispute ID in the URI and the evidence in the JSON request body.
- Request
- Response
1curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803/provide-evidence \2 -H 'Authorization: Bearer ACCESS_TOKEN' \3 -H 'Content-Type: multipart/form-data' \4 -F 'input={5 "evidences": [6 {7 "evidence_type": "PROOF_OF_FULFILLMENT",8 "evidence_info": {9 "tracking_info": [10 {11 "carrier_name": "FEDEX",12 "tracking_number": "122533485"13 }14 ]15 },16 "notes": "Test"17 }18 ]19 };type=application/json' \20 -F 'file1=@NewDoc.pdf;type=application/pdf'
A successful request returns the HTTP 200 OK status code and a JSON response body with a dispute link.
For information about dispute reasons associated with evidence types, see dispute reasons. For additional information, see provide evidence in the API reference.
Escalate dispute to claim
If either party is unsatisfied with the other party's response during the inquiry stage, they can escalate the dispute to a PayPal claim to resolve it. After this, the dispute moves to the claim stage.
You need to specify the dispute ID in the URL and include a note about the escalation in the JSON request body.
- Request
- Response
1curl "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-R-KPE-22563488/escalate" \2 -H "Content-Type: application/json" \3 -H "Authorization: Bearer ACCESS_TOKEN" \4 -d '{5 "note": "Escalating to PayPal claim for resolution."6}'
A successful request returns the HTTP 200 OK status code and a JSON response body that includes a link to the dispute.
Appeal dispute
If a merchant loses a dispute for any reason, they can appeal the lost dispute by ID if the case is appealable. To know whether a dispute is appealable, the merchant can refer to the HATEOAS links returned as part of the dispute details response for that dispute.
The merchant can appeal the dispute using the appeal dispute API. Specify the dispute ID in the URL and submit new evidence as a document or notes in the JSON request body. The evidence can include:
- Proof of delivery: Includes a tracking number.
- Proof of refund: Includes a refund ID and can also include notes or logs.
The maximum length of notes can be 2000 characters. For constraints and rules regarding documents, see documents.
- Request
- Response
1curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803/appeal \2 -H 'Content-Type: multipart/form-data' \3 -H 'Authorization: Bearer ACCESS_TOKEN' \4 -F 'input={5 "evidences": [6 {7 "evidence_type": "PROOF_OF_FULFILLMENT",8 "evidence_info": {9 "tracking_info": [10 {11 "carrier_name": "FEDEX",12 "tracking_number": "122533485"13 }14 ]15 },16 "notes": "Test"17 }18 ]19 };type=application/json' \20 -F 'file1=@NewDoc.pdf;type=application/pdf'
For any additional information, see appeal dispute in the API reference.
Acknowledge returned item
For a dispute labeled MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED
, the merchant can offer a full refund to the customer in exchange for the return of the item using the make offer API. The acknowledge return item response option becomes available to the merchant after the buyer reports to PayPal that they have shipped the item for return. The merchant can use the acknowledge returned item API to acknowledge the item return.
To know more about the various acknowledgment types, see acknowledgment type.
- Request
- Response
1curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-000-000-651-454/acknowledge-return-item \2-H 'Content-Type: application/json' \3-H 'Authorization: Bearer ACCESS_TOKEN' \4-d '{5 "note": "I have received the item back.",6 "acknowledgement_type": "ITEM_RECEIVED"7}'
A successful request returns the HTTP 200 OK status code and a JSON response body that includes a link to the dispute.
For additional information, see acknowledge returned item in the API reference.
Dispute reasons
The information required from the merchant to contest a dispute or chargeback varies depending on the dispute reason. While the following tables offer a broad overview of the information typically sought initially, confirming the specific evidence_type
under evidence requested by PayPal before submission is crucial. Review the evidence with the source REQUESTED_FROM_SELLER
to identify the evidence requested by the merchant.
It's important to note that PayPal may request additional information from the merchant multiple times throughout the dispute's lifecycle. If further clarification is required, the case status will transition to WAITING_FOR_SELLER_RESPONSE
. PayPal communicates details about the sought-after information through the evidence_type
, with the source being REQUESTED_FROM_SELLER
. See evidence.
MERCHANDISE_OR_SERVICE_NOT_RECEIVED
The customer did not receive the merchandise or service.
Evidence type | Required |
---|---|
PROOF_OF_FULFILLMENT |
note or document . For example, a document can be a proof of delivery signature or a proof of receipt copy.
|
PROOF_OF_REFUND |
|
MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED
The customer reports that the merchandise or service was not as described.
Evidence type | Required |
---|---|
OTHER |
A |
PROOF_OF_REFUND |
A set of |
UNAUTHORISED
The customer did not authorize purchase of the merchandise or service.
Evidence type | Required |
---|---|
PROOF_OF_FULFILLMENT |
|
PROOF_OF_REFUND |
The |
OTHER |
A |
CREDIT_NOT_PROCESSED
The credit transaction was not processed for the customer.
Evidence type | Required |
---|---|
PROOF_OF_REFUND |
The refund ID. |
OTHER |
A |
DUPLICATE_TRANSACTION
The transaction was a duplicate.
Evidence type | Required |
---|---|
PROOF_OF_REFUND |
The refund ID. |
OTHER |
A |
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 |
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 |
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 |
OTHER
Evidence type | Required |
---|---|
PROOF_OF_REFUND |
The refund ID. |
OTHER |
A |
Documents
The following rules apply to document file types and sizes:
- The party can upload up to 50 MB of files per request.
- Individual files must be smaller than 10 MB.
- The supported file formats are JPG, JPEG, GIF, PNG, and PDF.
Get started with sandbox
To test disputes on the sandbox, disputes API provides some sandbox-only APIs to facilitate the testing process. Additional setup is required before merchants can start creating disputes in the sandbox.
Sandbox-only methods
In the sandbox, you can create a dispute, update the dispute status, or settle the dispute. To create a dispute in the sandbox, set up buyer-side credentials. You do not need to set up the buyer-side credentials to update the dispute status or settle a dispute. For more information, see update dispute status and settle dispute in the API reference.
Set up buyer-side credentials to create a dispute in the sandbox
To create a dispute in the sandbox, set up buyer-side credentials using the following steps:
- Configure your REST app
Set up your REST app with the following scope:
https://uri.paypal.com/services/disputes/create
= DISPUTE_CREATE
Contact your PayPal account manager to enable this setting.
- Get permission from the buyer
To get permission from the buyer to create disputes on their behalf, complete the steps:
- To create a Log in with PayPal button, follow the steps to 'Enable Log in with PayPal' and 'Add Log in with PayPal button' from the Log in with PayPal integration guide.
- In Step 2, choose the Generate button option for a quicker setup. This will create a button for you using your application ID (client ID). Set the scope to
openid
, and ensure the return URL matches the one configured for your application in Step 1 of the guide. - Create a personal sandbox account to use as a buyer's account. Log in with this account after clicking on the generated button and providing consent after login.
- Generate access token
Use the following code to generate an access token. Use the CLIENT_ID
and secret access token for the merchant to access the PayPal Dispute API.
1curl -v -X POST "https://api-m.sandbox.paypal.com/v1/oauth2/token" \2 -u "CLIENT_ID:CLIENT_SECRET" \3 -H "Content-Type: application/x-www-form-urlencoded" \4 -d "grant_type=client_credentials"
4. Generate JSON web token for PayPal authorization assertion
Use the following HTML code to generate the JSON Web Token (JWT). You can run this code in any HTML sandbox environment or save it as an HTML file to open in a browser. Before running the code, replace CLIENT_ID
with the merchant's REST API client ID and BUYER_EMAIL
with the buyer's email address. The JSON Web Token is generated as output.
1<span id='cwppButton'></span>2<html>3 <script>4 function base64url(source) {5 var encodedSource = btoa(source);6 encodedSource = encodedSource.replace(/=+$/, '');7 encodedSource = encodedSource.replace(/\+/g, '-');8 encodedSource = encodedSource.replace(/\//g, '-');9 return encodedSource;10 }11 function generateJWT() {12 var header = {"alg": "none", "typ": "JWT"};13 var data = {"iss":"CLIENT_ID", "email" : "BUYER_EMAIL" };14 document.write(base64url(JSON.stringify(header)) + "." +15 base64url(JSON.stringify(data)) + ".");16 }17 </script>18 <body onload="generateJWT()"/>19<html>
5. Create a transaction using the buyer's account
Login to the buyer account you created in Step 2 and use it to send money to the business account you used to create the application.
This is the transaction you will use to create a dispute. Go to the sandbox activity page for the personal account and note the transaction ID of the transaction you just performed. In the next step, use this transaction ID to create a dispute.
6. Create the dispute
Use the following cURL code to create the dispute, replacing the ACCESS_TOKEN
, JWT-TOKEN
, and BUYER-TRANSACTION-ID
with their respective values. The ACCESS_TOKEN
is the access token from Step 3, JWT-TOKEN
is the JSON Web Token from Step 4, and the BUYER-TRANSACTION-ID
is the buyer transaction ID from Step 5.
1curl -X POST "https://api-m.sandbox.paypal.com/v1/customer/disputes" \2-H "Authorization: Bearer ACCESS_TOKEN" \3-H 'Content-Type: multipart/form-data' \4-H "PayPal-Auth-Assertion: JWT-TOKEN" \5-F 'input={"disputed_transactions": [{6 "buyer_transaction_id": "BUYER-TRANSACTION-ID"7 }],8 "reason": "MERCHANDISE_OR_SERVICE_NOT_RECEIVED",9 "dispute_amount": { "currency_code":"USD", "value": "7.50" },10 "extensions": {11 "merchant_contacted": true,12 "merchant_contacted_outcome": "NO_RESPONSE",13 "merchandize_dispute_properties": {14 "issue_type": "PRODUCT"15 }16 }17};type=application/json'
7. Create a chargeback
Use the following code to pass the access token and the seller transaction ID to create a chargeback. The ACCESS_TOKEN
is the access token from Step 3, and SELLER_TRANSACTION_ID
can be obtained from the activity page of the business account you used to send money in Step 5. Ensure you use a credit card for the send money operation to make the transaction eligible for a chargeback.
Note: Update the receive_date
and money_movement_date
to the current value and response_date
to a future value.
1curl -X POST "https://api-m.sandbox.paypal.com/v2/customer-support/process-chargeback" \2-H "Authorization: Bearer <ACCESS_TOKEN>" \3-H "Content-Type: application/json" \4--data-raw '{5 "adjacency": "PAYPAL",6 "file_layout": "ATCK_CB",7 "financial_institution": {8 "processor": "FDMS"9 },10 "transaction": {11 "id_enc": "<SELLER_TRANSACTION_ID>",12 "amount": {13 "currency_code": "EUR",14 "value": "100"15 }16 },17 "instrument": {18 "card_brand": "VISA",19 "credit_card_transaction_id": "",20 "external": false21 },22 "dispute": {23 "id": null,24 "stage": "CHARGEBACK",25 "response_date": "2023-07-16T12:05:22.544Z",26 "status": "2",27 "amount": {28 "currency_code": "EUR",29 "value": "15"30 },31 "receive_date": "2023-06-16T12:05:22.544Z",32 "event_code": "CHARGEBACK_INITIATED",33 "money_movement_date": "2023-06-16T12:05:22.544Z",34 "event_type": "DEBIT",35 "chargeback_type": "REPORTED_TO_PROCESSOR",36 "processor_info": {37 "reference_number": "31639435342702423793399",38 "reason_code": "4853",39 "notes": "TEST_MEMO",40 "additional_info": []41 }42 },43 "processor_auxiliary_info": {}44}'
Change the dispute reason
Set up buyer-side credentials to create a dispute in the sandbox
To change the reason for a dispute in the sandbox, set up buyer-side credentials using the following steps:
1. Configure your REST app
Set up your REST app with the following scope:
https://uri.paypal.com/services/disputes/update-buyer
= UPDATE_BUYER
Contact your PayPal account manager to enable this setting.
2. Get permission from the buyer
To get permission from the buyer to create disputes on their behalf, complete the following steps:
- To create a Log in with PayPal button, follow the steps to 'Enable Log in with PayPal' and 'Add Log in with PayPal button' from the Log in with PayPal integration guide.
- In Step 2, choose the Generate button option for a quicker setup. This will create a button for you using your application ID (client ID). Set the scope to
openid
, and ensure the return URL matches the one configured for your application in Step 1 of the guide. - After you click on the generated button, log into the buyer account associated with the dispute requiring a change reason and provide consent after you log in.
3. Generate access token
Use the following code to generate an access token. Use the CLIENT_ID
and CLIENT_SECRET
(secret key) for the merchant to access the PayPal Dispute API.
1url -v -X POST "https://api-m.sandbox.paypal.com/v1/oauth2/token" \2 -u "CLIENT_ID:CLIENT_SECRET" \3 -H "Content-Type: application/x-www-form-urlencoded" \4 -d "grant_type=client_credentials"
4. Generate JSON web token for PayPal authorization assertion
Use the following HTML code to generate the JSON Web Token (JWT).
You can run this code in any HTML sandbox environment or save it as an HTML file to open in a browser. Before running the code, replace CLIENT_ID
with the merchant's REST API client ID and BUYER_EMAIL
with the buyer's email address. The output contains the JSON Web Token.
1<span id='cwppButton'></span>2<html>3 <script>4 function base64url(source) {5 var encodedSource = btoa(source);6 encodedSource = encodedSource.replace(/=+$/, '');7 encodedSource = encodedSource.replace(/\+/g, '-');8 encodedSource = encodedSource.replace(/\//g, '-');9 return encodedSource;10 }11 function generateJWT() {12 var header = {"alg": "none", "typ": "JWT"};13 var data = {"iss":"CLIENT_ID", "email" : "BUYER_EMAIL" };14 document.write(base64url(JSON.stringify(header)) + "." +15 base64url(JSON.stringify(data)) + ".");16 }17 </script>18 <body onload="generateJWT()"/>19<html>
5. Change the dispute reason
Use the following cURL code to change the reason for a dispute.
Replace ACCESS_TOKEN
, JWT-TOKEN
, BUYER-TRANSACTION-ID
, and DISPUTE-ID
with their respective values:
ACCESS_TOKEN
: The access token obtained from Step 2.JWT-TOKEN
: The JWT obtained from Step 3.DISPUTE-ID
: The ID of the dispute for which you want to change the reason.BUYER-TRANSACTION-ID
: The buyer's transaction ID associated with the dispute.
1curl -X POST "https://api-m.sandbox.paypal.com/v1/customer/disputes/DISPUTE-ID/change-reason" \2-H "Authorization: Bearer ACCESS_TOKEN" \3-H "Content-Type: multipart/related" \4-H "PayPal-Auth-Assertion: JWT-TOKEN" \5-F 'input={6 "reason": "MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED",7 "note": "change reason":8 [9 "BUYER-TRANSACTION-ID"10 ],11 "item_info":12 [13 {14 "item_name": "item 1",15 "item_quantity": "2",16 "reason": "MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED",17 "item_type": "PRODUCT",18 "product_details":19 {20 "sub_reason": "DELAYED",21 "category": "OTHER"22 },23 "expected_refund":24 {25 "currency_code": "USD",26 "value": "10"27 }28 }29 ]30};type=application/json'
Negative testing for disputes
You can use simulation to test your disputes. For more information, see Test Disputes.
Documents
The following rules apply to document file types and sizes:
- The party can upload up to 50 MB of files per request.
- Individual files must be smaller than 10 MB.
- The supported file formats are JPG, JPEG, GIF, PNG, and PDF.