Disputes
Occasionally, something goes wrong with a customer's order. To dispute a charge, a customer can create a dispute with PayPal. PayPal merchants, partners, and…
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
Occasionally, something goes wrong with a customer's order. To dispute a charge, a customer can create a dispute with PayPal. PayPal merchants, partners, and external developers can use the PayPal Disputes API to manage customer disputes. Note: In the live environment, merchants cannot create disputes but can only respond to customer-created disputes. However, merchants can create disputes in the sandbox environment. When you create an app, enable Disputes in the App feature options section. A customer can also ask his or her bank or credit card company to dispute and reverse a charge, which is known as a chargeback . For more information, see Disputes, claims, chargebacks, and bank reversals . When a customer disputes a charge, you can use this API to provide evidence that the charge is legitimate. To provide evidence or appeal a dispute, you submit a proof of delivery or proof of refund document or notes, which can include logs. Normally, an agent at PayPal creates a dispute, updates the dispute status, and settles disputes, but now you can run test cases in the sandbox that complete these operations. Important: The create, cancel, compute metrics, change reason, and validate eligibility methods are available as a limited-release solution at this time. For more information, reach out to your PayPal account manager. For details, see Disputes Overview documentation.
Endpoints 15
disputes
- GETList disputes
/v1/customer/disputes?start_time=Current date and time&disputed_transaction_id=string&page_size=10&next_page_token=The first page of data&dispute_state=string&update_time_before=string&update_time_after=stringLists disputes with a summary set of details, which shows the <code>dispute_id</code>, <code>reason</code>, <code>status</code>, <code>dispute_state</code>,… - GETShow dispute details
/v1/customer/disputes/:idShows details for a dispute, by ID.<blockquote><strong>Note:</strong> The fields that appear in the response depend on the access. For example, if the… - PATCHPartially update dispute
/v1/customer/disputes/:idPartially updates a dispute, by ID. Seller can update the communication_detail value or The partner can add the partner action information.
disputes-actions
- POSTProvide evidence
/v1/customer/disputes/:id/provide-evidenceProvides evidence for a dispute, by ID. A merchant can provide evidence for disputes with the <code>WAITING_FOR_SELLER_RESPONSE</code> status while customers… - POSTAppeal dispute
/v1/customer/disputes/:id/appealAppeals a dispute, by ID. To appeal a dispute, use the <code>appeal</code> link in the <a href="/docs/api/reference/api-responses/#hateoas-links/">HATEOAS… - POSTAccept claim
/v1/customer/disputes/:id/accept-claimAccepts liability for a claim, by ID. When you accept liability for a claim, the dispute closes in the customer’s favor and PayPal automatically refunds money… - POSTSettle dispute
/v1/customer/disputes/:id/adjudicate<blockquote><strong>Important:</strong> This method is for sandbox use only.</blockquote> Settles a dispute in either the customer's or merchant's favor.… - POSTUpdate dispute status
/v1/customer/disputes/:id/require-evidence<blockquote><strong>Important:</strong> This method is for sandbox use only.</blockquote> Updates the status of a dispute, by ID, from… - POSTEscalate dispute to claim
/v1/customer/disputes/:id/escalateEscalates the dispute, by ID, to a PayPal claim. To make this call, the stage in the dispute lifecycle must be INQUIRY. - POSTSend message about dispute to other party
/v1/customer/disputes/:id/send-messageSends a message about a dispute, by ID, to the other party in the dispute. Merchants and customers can only send messages if the dispute_life_cycle_stage… - POSTMake offer to resolve dispute
/v1/customer/disputes/:id/make-offerMakes an offer to the other party to resolve a dispute, by ID. To make this call, the stage in the dispute lifecycle must be INQUIRY. If the customer accepts… - POSTAccept offer to resolve dispute
/v1/customer/disputes/:id/accept-offerThe customer accepts the offer from merchant to resolve a dispute, by ID. PayPal automatically refunds the amount proposed by merchant to the customer. - POSTDeny offer to resolve dispute
/v1/customer/disputes/:id/deny-offerDenies an offer that the merchant proposes for a dispute, by ID. - POSTAcknowledge returned item
/v1/customer/disputes/:id/acknowledge-return-itemAcknowledges that the customer returned an item for a dispute, by ID. A merchant can make this request for disputes with the… - POSTProvide supporting information for dispute
/v1/customer/disputes/:id/provide-supporting-infoProvides supporting information for a dispute, by ID. A merchant or buyer can make this request for disputes if they find the provide-supporting-info link in…
API details
- Base URL
https://api-m.sandbox.paypal.comhttps://api-m.paypal.com- Authentication
- OAuth 2.0 (client credentials flow) with 11 scopes
- Operations
- 15 operations on 14 pathsPOST 12GET 2PATCH 1
- Main resources
- disputes-actions 12disputes 3
- Response formats
application/json- Description format
- OpenAPI 3.0.3, API version
1.11 - Links
- Documentation · OpenAPI document
- Listed from
- PayPal's published OpenAPI description (paypal/paypal-rest-api-specifications) (Apache-2.0)
How to test the Disputes in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Disputes collection, without the publisher's secrets.
- Add your credentialsThis API uses OAuth 2.0 (client credentials flow) with 11 scopes. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “List disputes” (GET /v1/customer/disputes?start_time=Current date and time&disputed_transaction_id=string&page_size=10&next_page_token=The first page of data&dispute_state=string&update_time_before=string&update_time_after=string), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Disputes?
Occasionally, something goes wrong with a customer's order. To dispute a charge, a customer can create a dispute with PayPal. PayPal merchants, partners, and… It is listed under Payments and has 15 endpoints.
Who publishes the Disputes?
It is listed from PayPal's public API description (an OpenAPI document), not published by PayPal on Swastik Codes. Anyone who controls paypal.com can claim the profile by adding a DNS TXT record.
What is the base URL of the Disputes?
Its description lists 2 base URLs: https://api-m.sandbox.paypal.com, https://api-m.paypal.com. The first is the usual one; the others are typically sandbox or regional servers.
How do I authenticate with the Disputes?
With OAuth 2.0 (client credentials flow) with 11 scopes.
How many endpoints does the Disputes have?
15 operations on 14 paths (12 POST, 2 GET, 1 PATCH). The largest groups are disputes-actions, disputes.
Is forking the Disputes free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.