Buyer-Side Disputes

Set up buyer-side credentials to create a dispute in the sandbox

DocsCurrentLast updated: October 1st 2021, @ 12:45:16 pm


To create a dispute in the sandbox, you must set up buyer-side credentials using the following steps.

1. Configure your REST app

Set up your REST app with the following scope:

https://uri.paypal.com/services/disputes/create = DISPUTE_CREATE

2. Get permission from the buyer

To get permission from the buyer to create disputes on their behalf, save the following code as HTML to create a Log in with PayPal button. Set the CLIENT_ID and URL_SET_IN_APP from the REST app. Then, log in as the buyer and accept consent.

<span id='cwppButton'></span>
<script src="https://www.paypalobjects.com/js/external/connect/api.js"></script>
<script>
    paypal.use( ['login'], function (login) {
        login.render ({
            'appid': 'CLIENT_ID',
            'authend': 'sandbox',
            'scopes': 'openid https://uri.paypal.com/services/disputes/create https://uri.paypal.com/services/disputes/read-buyer'
            'containerid': 'cwppButton',
            'locale': 'en-us',
            'buttonType': 'CWP',
            'buttonSize': 'lg',
            'returnurl': 'URL_SET_IN_APP'
        });
    });
</script>

3. Generate access token

Use the following code to generate an access token. Use the CLIENT_ID and secret access token for the merchant to access the PayPal Dispute API.

curl -X POST \ https://api-m.sandbox.paypal.com/v1/oauth2/token \
-H 'Authorization: Basic <<Your Base64-encoded CLIENT_ID:Secret>>' \
-H 'Content-Type: x-www-form-urlencoded' \
-d grant_type=authorization_code

4. Generate JSON web token for PayPal Authorization Assertion

Use the following code to generate the JSON web token. The CLIENT_ID is from the merchant's REST API. The email is the buyer's email address. The JSON web token is given as output.

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

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

5. Get the buyer transaction ID

Using the following code, pass the access token from step 2, the JSON web token from step 3, and the seller transaction ID from the transaction details of the transaction in dispute. This API returns the valid type of disputes that can be created for a given transaction. Also, the buyer transaction ID is returned.

curl -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes/validate-eligibility \
-H 'Authorization: Bearer <<Access Token>>' \
-H 'Content-Type: application/json' \
-H 'PayPal-Auth-Assertion: <<JWT Token>>' \
-d '{
  "encrypted_transaction_id": "<<Seller Transaction ID>>"
}'

6. Create the dispute

Using the following code, pass the access token from step 2, the JSON web token from step 3, and the buyer transaction ID from step 4 to create the dispute.

curl -X POST 'https://api-m.sandbox.paypal.com/v1/customer/disputes' \
-H 'Authorization: Bearer <ACCESS TOKEN>' \
-H 'Content-Type: multipart/related' \
-H 'PayPal-Auth-Assertion: <JWT TOKEN>> \
-F 'input={"disputed_transactions":[{
          "buyer_transaction_id":"<BUYER TRANSACTION ID>"
        }],
        "reason": "MERCHANDISE_OR_SERVICE_NOT_RECEIVED",
        "dispute_amount": { "currency_code":"USD", "value": "7.50" },
        "extensions": {
          "merchant_contacted": true,
          "merchant_contacted_outcome": "NO_RESPONSE",
          "merchandize_dispute_properties": {
              "issue_type": "PRODUCT"
          }
        }
};
type=application/json'
ReferencePayPal.comPrivacyCookiesSupportLegalContact