Customer Disputes and Integration Testing

Learn how to use sandbox accounts, the Customer Disputes API, and acceptance test criteria to test the dispute management flow for your integration.

Test entities

To test the dispute management flow, you need customer, merchant, and PayPal entities.

You simulate these entities and their activities through a set of sandbox accounts and Customer Disputes API calls:

Entity	Description
Customer	Complete customer actions through manual interaction with a personal sandbox account that represents the customer.
Merchant	Complete merchant actions through manual interaction with a business sandbox account that represents the merchant and Customer Disputes API calls.
PayPal	Complete the typical PayPal actions through the sandbox-only API calls.

Test steps

Step	Entity	Description
1.	Customer	Set up a personal sandbox account to represent the customer in a transaction.
2.	Merchant	Set up a business sandbox account to represent the merchant in a transaction.
3.	Merchant	Log in to the merchant's business sandbox account and navigate to the resolution center to create dispute reasons.
4.	Customer	Log in to the customer sandbox account to create a PayPal transaction.
5.	Customer	From the customer's sandbox account, navigate to either the resolutions center or a transaction and create a dispute.
6.	Merchant	To make an offer to the customer through the resolution center, log in to the merchant sandbox account. You can also call the Customer Disputes API to: List disputes and show details for a single dispute. Send message to the other party, make an offer to resolve the dispute, and escalate a dispute to a claim. Provide evidence, accept a claim, and appeal a dispute.
7.	Customer	To accept the merchant's offer, log in to the customer sandbox account.
8.	PayPal	To complete actions that a PayPal agent normally handles, call these sandbox-only Customer Disputes API methods: Create a dispute Update the dispute status so either a customer or merchant can provide evidence Settle a dispute

Create dispute

In the sandbox, you can create a dispute to test the dispute management workflow for your integration.

Update dispute status

In the sandbox, you can update the state of a dispute, by ID, to either WAITING_FOR_BUYER_RESPONSE or WAITING_FOR_SELLER_RESPONSE. This state change enables either the customer or merchant to submit evidence for the dispute.

You specify the dispute ID in the URI and include the action in the JSON request body. The action indicates whether the state change enables the customer or merchant to submit evidence:

If the action is BUYER_EVIDENCE, the state updates to WAITING_FOR_BUYER_RESPONSE.
If the action is SELLER_EVIDENCE, the state updates to WAITING_FOR_SELLER_RESPONSE.

For example, the following request makes a state change that enables the customer to submit evidence:

curl -v -X POST https://api.sandbox.paypal.com/v1/customer/disputes/PP-D-27803/require-evidence \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token" \
  -d '{
  "action": "BUYER_EVIDENCE"
}'

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-D-27803"
  }]
}

Settle dispute

In the sandbox, you can settle a dispute, by ID, in either in the customer's or merchant's favor. Include the dispute ID in the request URI.

In the JSON request body, you include the outcome of the dispute, which is either BUYER_FAVOR or SELLER_FAVOR. A successful request returns the HTTP 200 OK status code and a JSON response body that includes a link to the dispute.