Set up accounts and environment

You can use the procedures in this section to ensure that your accounts and environment are set up to manage disputes.

Set up sandbox account

Resolution Center
Disputes API

Sign up for a developer account. On successful signup, PayPal automatically creates your sandbox environment. The sandbox environment is a test environment that helps you mimic real-world transactions.
Retrieve sandbox account credentials to log in to your PayPal sandbox account and access the Resolution Center. To do this:
1. Select Sandbox Accounts. By default, the environment includes a business and personal account. To create more sandbox accounts, you can select Create account.
2. Locate the account for which you want to get credentials, and select ⋮.
3. Select View/Edit Account to view the account email address and the system-generated password.
Sign in to your PayPal sandbox account using the personal sandbox credentials. In a separate browser session, sign in with the business sandbox credentials. When you test dispute workflows, use the personal account to create disputes and the business account to handle them. Verify the dispute status in both accounts.

Sign up for a developer account. On successful signup, PayPal automatically creates your sandbox environment. The sandbox environment is a test environment that helps you mimic real-world transactions. By default, the environment includes a business and personal account. When testing your app, you can use the personal account to create disputes and the business account to handle them. You can create additional business and personal accounts.
Set up the sandbox environment:
1. Go to your PayPal developer account and toggle to Sandbox.
2. Go to Apps & Credentials and select Create App.
3. Enter your app name, select Type as Merchant, select the sandbox business account to test your app, and select Create App. The app details page is displayed.
4. Go to Features > Other features. By default, the Customer disputes checkbox is selected. If not, select it.
5. Optional: Configure a webhook listener for the app and subscribe to events:
  1. In the app details page, go to Sandbox Webhooks.
  2. Select Add Webhook.
  3. Enter a Webhook URL (the server endpoint where notifications from PayPal are sent), select the events the app wants to subscribe to, and select Save.
  4. The webhook listener is successfully configured, and a Webhook ID is displayed. You can store the ID and use it in your app code to verify the source sending messages to your listener. For more information on webhooks, see Webhooks guide. For the list of disputes events that the app can subscribe to, see Webhook reference.
Retrieve sandbox app credentials: To integrate and test the Disputes API, you need the sandbox credentials (Client ID and Client secret) for your app. To retrieve them, see Get your client ID and client secret.
Retrieve sandbox account credentials: When you test your disputes integration end-to-end, you log in to your PayPal personal account, create a dispute, handle it through your PayPal business account, and check the dispute status in both accounts. You need sandbox login credentials for both accounts. For information on how to get these from your developer account, see Get sandbox account credentials.
Set up the development environment. This involves building your server, installing dependencies, verifying configuration files that the package managers use, and setting up the environment variables.

Set up buyer-side credentials

The procedures in this section apply only to the test simulations of the Disputes API.

To create disputes or change dispute reasons as a buyer using the Disputes API, you need to set up buyer-side credentials. To do this:

Configure your REST app.
Get buyer consent for your sandbox personal account.
Use PayPal-Auth-Assertion request header when you make API calls to create disputes or change dispute reasons as a buyer.

Configure your REST app

Contact your PayPal account manager to add the following scopes to your REST app:

Scope name	Scope	Description
`DISPUTE_CREATE`	`https://uri.paypal.com/services/disputes/create`	Scope to create a dispute.
`UPDATE_BUYER`	`https://uri.paypal.com/services/disputes/update-buyer`	Scope to change the dispute reason.

You need to obtain buyer consent to create disputes or change dispute reasons on behalf of your sandbox personal account (buyer) using the Disputes API. To do this:

Create a Log in with PayPal button:
1. Complete the steps to Enable Log in with PayPal in your PayPal developer account.
2. Complete the steps to Generate button. When you do this, you can configure the following options:
  - application ID (client ID) as your app’s client ID.
  - auth end point as sandbox.
  - scope as openid.
  - return URL should match the one configured for your REST app in the previous step.
Run your application.
Select Log in with PayPal on your application.
Log in with your sandbox personal account credentials as a buyer and approve the consent.

Use PayPal-Auth-Assertion request header

During the API test simulation, include the PayPal-Auth-Assertion request header in API calls to create disputes or change dispute reasons as a buyer.Generate the JSON Web Token (JWT) and pass it in this request header to identify the buyer.

Generate JWT for PayPal-Auth-Assertion

Replace the following in the HTML code provided:

CLIENT_ID with your app’s client ID.
BUYER_EMAIL with the buyer’s email address.

Run this code in any HTML sandbox environment or save it as an HTML file and open it in a browser. This generates a JWT that you can use in the PayPal-Auth-Assertion request header.

<span id='cwppButton'></span>
<html>
  <script>
    function base64url(source) {
      var encodedSource = btoa(source);
      encodedSource = encodedSource.replace(/=+$/, '');
      encodedSource = encodedSource.replace(/\+/g, '-');
      encodedSource = encodedSource.replace(/\//g, '-');
      return encodedSource;
    }
    function generateJWT() {
      var header = {"alg": "none", "typ": "JWT"};
      var data = {"iss":"CLIENT_ID", "email" : "BUYER_EMAIL" };
      document.write(base64url(JSON.stringify(header)) + "." +
      base64url(JSON.stringify(data)) + ".");
    }
  </script>
  <body onload="generateJWT()"/>
</html>

Set up live account

Resolution Center
Disputes API

Log in to your PayPal business account at the PayPal Business Dashboard. No additional setup or configuration is required to use the Resolution Center in the live environment.

Grow your business

Send payouts

Manage disputes

Analyze reports

Agentic commerce

Set up accounts and environment

Set up sandbox account

Set up buyer-side credentials

Configure your REST app

Use PayPal-Auth-Assertion request header

Generate JWT for PayPal-Auth-Assertion

Set up live account

Grow your business

Send payouts

Manage disputes

Analyze reports

Agentic commerce

​Set up sandbox account

​Set up buyer-side credentials

​Configure your REST app

​Get buyer consent

​Use PayPal-Auth-Assertion request header

Generate JWT for PayPal-Auth-Assertion

​Set up live account

Set up sandbox account

Set up buyer-side credentials

Configure your REST app

Get buyer consent

Use PayPal-Auth-Assertion request header

Set up live account