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:

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 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.

Feedback