PayPal

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…

Payments#openapi

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.com
https://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

How to test the Disputes in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Disputes collection, without the publisher's secrets.
  3. 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.
  4. 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.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.