Request Third-Party Permissions through the Permissions Service

Important: Adaptive Accounts and Adaptive Payments are now limited release products. They are restricted to select partners for approved use cases and should not be used for new integrations without guidance from PayPal.

The Permissions Service enables you to request permission from a third-party to execute PayPal API requests on their behalf. When a third-party grants you permissions, PayPal assigns you a set of security tokens to use when you make calls on behalf of a third party.

For information on how to use the tokens to make third-party calls, see Creating and Sending an Invoice on Behalf of a Third Party.

This guide sets up third-party permissions for Invoicing Service calls. However, modify the RequestPermissions scope parameter to request permissions for any of the supported PayPal API operations.

Tip: Third-party merchants can grant you permission to execute many different PayPal operations on their behalf. The Permissions Service divides PayPal API operations into different sets using Group IDs, and permissions are granted based on the Group ID value(s) you specify when you make a RequestPermissions call. For complete details on Group ID values, see the Permissions Service Developer Guide.

Process overview

Imagine you're a developer creating an invoicing system that manages the invoicing for third-party merchants. To use the PayPal Invoicing Service operations, you'll need to obtain permission from the merchants to send invoicing calls on their behalf.

Use this call flow to request PayPal API permissions:

  1. Call RequestPermissions to receive from PayPal a Request Token. The token is associated with the Group ID(s) specified in the call.
  2. Direct the third-party to PayPal so they can log in and grant the requested permissions. If granted, PayPal returns a Verification Code.
  3. Call GetAccessToken with the Request Token and Verification Code. PayPal responds with the permission credentials: an Access Token and Token Secret.
  4. Use the permission credentials to create an X-PAYPAL-AUTHORIZATION header, which you use in the calls you make on behalf of the third-party.

Tip: For instructions on using the PayPal APIs, how to use the Sandbox for testing, and how to move your application into production, see Apps 101.

Do it

The following example gets permissions to make Invoicing Service calls on behalf of a third party. For testing purposes, the example uses the PayPal Sandbox environmnet. To create and test this example in the Sandbox, create three test accounts:

  • The API Caller account (owner of the applicaiton making the calls)
  • Receiver account (the Merchant)
  • Sender account (the Buyer)

The API call inputs are formatted with cURL notation and are commented for readability.

  1. Call RequestPermissions using the inputs shown in the following snippet:

    Request

     curl https://svcs.sandbox.paypal.com/Permissions/RequestPermissions \
       -s \
       --insecure \
       -H "X-PAYPAL-SECURITY-USERID: caller_UID"     # UserID from the Caller account \
       -H "X-PAYPAL-SECURITY-PASSWORD: caller_PSWD"  # Password from the Caller account \
       -H "X-PAYPAL-SECURITY-SIGNATURE: caller_Sig"  # Signature from the Caller account \
       -H "X-PAYPAL-REQUEST-DATA-FORMAT: JSON" \
       -H "X-PAYPAL-RESPONSE-DATA-FORMAT: JSON" \
       -H "X-PAYPAL-APPLICATION-ID: APP-80W284485P519543T"    # Sandbox AppID \
       \
       # ** Payload **
       -d '{
             "requestEnvelope": {
               "errorLanguage":"en_US"   # Language of returned errors
             },
             "scope":"INVOICING",        # Group IDs get permissions for differnet API sets
             "callback":"https://example.com"/grant.html"  # page 3rd-party sees after granting permissions
           }'
     

    Response

     {
       "responseEnvelope":{
         "ack":"Success",
         // ...
       },
       "token":"RequestToken"
     }
     

    The RequestPermissions call returns a Request Token that you use in subsequent calls.

    Tip: The snippets in this guide address the PayPal Sandbox environment. You can run the sample code by setting up two Sandbox Business accounts: one to represent the third-party merchant (the Receiver) and the other to represent you as the API caller.

  2. After getting the Request Token, direct the third-party (whose permission you are seeking) to PayPal so they can review your permissions request. With luck, they will grant you the permissions you seek.

    The following Sandbox URL (wrapped for readability) redirects the third party to PayPal so they can log in and grant you the respective permissions:

     https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_grant-permission&request_token=RequestToken
     

    To see this work in the Sandbox, log into the resulting Sandbox page using the credentials of the Sandbox Receiver account (be sure to log into the Sandbox using your main log-in credentials before attempting to log in with a test account). PayPal details the permissions request on the resulting screen.

    When the third-party clicks the Grant Permission button, PayPal returns a Verification Code. The third-party is redirected to the page specified by the callback-http value of your original RequestPermissions call.

  3. Call GetAccessToken with the Request Token and the Verification Code:

    GetAccessToken HTTP headers

     curl https://svcs.sandbox.paypal.com/Permissions/GetAccessToken \
       -s \
       --insecure \
       -H "X-PAYPAL-SECURITY-USERID: caller_UID"     # UserID from the Caller account \
       -H "X-PAYPAL-SECURITY-PASSWORD: caller_PSWD"  # Password from the Caller account \
       -H "X-PAYPAL-SECURITY-SIGNATURE: caller_Sig"  # Signature from the Caller account \
       -H "X-PAYPAL-REQUEST-DATA-FORMAT: JSON" \
       -H "X-PAYPAL-RESPONSE-DATA-FORMAT: JSON" \
       -H "X-PAYPAL-APPLICATION-ID: APP-80W284485P519543T"    # Sandbox AppID \
       \
       # ** Payload ** \
       -d '{
             "requestEnvelope": {
               "errorLanguage":"en_US"   # Language of returned errors
             },
             "token":"RequestToken",
             "verifier":"VerificationCode"  # code returned when permissions were granted
           }'
     

    Response

     {
       "responseEnvelope":{
         "ack":"Success",
         // ...
       },
       "scope":["INVOICING"],
       "token":"AccessToken",
       "tokenSecret":"TokenSecret"
     }
     

    GetAccessToken returns both an Access Token and a Token Secret. When you call a PayPal API operation on behalf of a third party, you need to use both of these values to create the X-PAYPAL-AUTHORIZATION header that you supply with the call. This HTTP header indicates that you have permission to make the call on behalf of the account holder.

That's it, you have now have the permission credentials you need to make Invoicing calls on behalf of a third party. Be sure to save both the Access Token and Token Secret in a secure place that you access them later as needed.

Creating the authorization header

Once you have the permission credentials, use them to create a time-dependent X-PAYPAL-AUTHORIZATION header that you include with each API call you make on behalf of a third party. The value of X-PAYPAL-AUTHORIZATION depends on the current time, your permission credentials, and the call endpoint. You create an individual OAuth header value for each call you make on behalf of a third party.

The X-PAYPAL-AUTHORIZATION header is created from the following set of values:

  • The Access Token from the GetAccessToken response
  • An OAuth signature generated from the following information:
    • Caller (your) API user name
    • Caller (your) API password
    • Access Token from the GetAccessToken response
    • Token Secret from the GetAccessToken response
    • Endpoint for the PayPal request (such as https://api.paypal.com/nvp)
    • The HTTPS delivery method (such as POST)
    • Request parameters associated with the request (if using GET)
  • An OAuth timestamp

Tip: You can use a certificate instead of the API user name and API signature.

Here is an example header, wrapped for readability:

X-PAYPAL-AUTHORIZATION=
token=AccessToken,
signature=OAuthSignature,
timestamp=CurrentOAuthTimestamp

The PayPal SDKs provide routes in Java, PHP, and C# to help you create X-PAYPAL-AUTHORIZATION header values. For example, the PPAuthenticationManager.php file in the Permissions PHP SDK contains the following code to generate the header value:

<?php
// ...

$headers_arr[] = "X-PAYPAL-AUTHORIZATION: " . $this->generateAuthString($apiCred,
$accessToken, $tokenSecret, $url);

// ...

private function generateAuthString($apiCred, $accessToken, $tokenSecret, $endpoint)
{
  $callerUid = $apiCred->getUserName();
  $callerPswd = $apiCred->getPassword();
  $auth = new AuthSignature();
  $response = $auth->genSign($callerUid,$callerPswd,$accessToken,$tokenSecret,'POST',$endpoint);
  $authString = "token=" . $accessToken . ",signature=" . $response['oauth_signature'] . ",timestamp=" . $response['oauth_timestamp'];

  return $authString;
}

// ...
?>

Learn more

Refer to the following resources for more on the Permissions Service:

Feedback