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

Use the Permissions Service API to obtain permission to execute PayPal API operations on behalf of PayPal account holders. You can use PayPal SDKs to generate authentication headers for PayPal Adaptive Payment and Adaptive Accounts APIs.

Obtaining Permissions

To obtain permissions from an account holder, you call RequestPermissions to make the request, redirect to PayPal to enable the account holder to approve the request, and call GetAccessToken to obtain the permissions and an access token. The access token enables you to create a signature for calling API operations as a third party, determine the permissions you can access, and cancel access to the permissions.

The following diagram shows the basic execution flow for obtaining permission as a third party to PayPal and an account holder:

To obtain permissions from an account holder, follow these steps:

  1. Set up your request and call the RequestPermissions API operation.

    • Specify the return URL in the callback field.

    • Specify one or more group IDs, such as EXPRESS_CHECKOUT, in the scope field; one string per group ID.

    • Send the request to the https://svcs.paypal.com/Permissions/RequestPermission endpoint.

      Note: Use https://svcs.sandbox.paypal.com/Permissions/... for the Sandbox.

      curl https://svcs.sandbox.paypal.com/Permissions/RequestPermissions \
        -s  \
        --insecure \
        -H "X-PAYPAL-SECURITY-USERID: api_username" \
        -H "X-PAYPAL-SECURITY-PASSWORD: api_password" \
        -H "X-PAYPAL-SECURITY-SIGNATURE: api_signature" \
        -H "X-PAYPAL-REQUEST-DATA-FORMAT: NV" \
        -H "X-PAYPAL-RESPONSE-DATA-FORMAT: NV" \
        -H "X-PAYPAL-APPLICATION-ID: app_id" \
        -d requestEnvelope.errorLanguage=en_US \
        -d scope=EXPRESS_CHECKOUT \
        -d callback=https://example.com/return
      

    PayPal responds with a request token that you use in following steps to obtain an access token.

    Note: The request token from this step is different than the access token, which you use to access permissions that already have been granted.

  2. Redirect the account holder's browser to PayPal and include the request token in the request_token parameter.

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

    PayPal initiates granting permissions. When the account holder grants permissions, PayPal returns a verification code, which you use in the next step.

    Note: The verification code expires in about 15 minutes.

  3. Set up your request and call the GetAccessToken API operation.

    • Specify the request token in the token field.

    • Specify the verification code in the verifier field.

    • Send the request to https://svcs.paypal.com/Permissions/GetAccessToken.

      curl https://svcs.sandbox.paypal.com/Permissions/GetAccessToken \
        -s  \
        --insecure \
        -H "X-PAYPAL-SECURITY-USERID: api_username" \
        -H "X-PAYPAL-SECURITY-PASSWORD: api_password" \
        -H "X-PAYPAL-SECURITY-SIGNATURE: api_signature" \
        -H "X-PAYPAL-REQUEST-DATA-FORMAT: NV" \
        -H "X-PAYPAL-RESPONSE-DATA-FORMAT: NV" \
        -H "X-PAYPAL-APPLICATION-ID: app_id" \
        -d requestEnvelope.errorLanguage=en_US \
        -d token=token \
        -d verifier=code
      

    PayPal responds with the scope, which is a list of the permissions granted by the account holder, and an access token and associated secret.

You use the access token and associated secret to create an authentication header, X-PAYPAL-AUTHORIZATION if your API is hosted at svcs.paypal.com or X-PP-AUTHORIZATION if your API is hosted at api.paypal.com. When you call PayPal API operations, the authentication header specifies whether you have permission to make the call on behalf of the account holder.

Generating Signatures for the Authentication Header

After you have an access token and associated secret, you can create an authentication header, X-PAYPAL-AUTHORIZATION, and use it for calls to PayPal APIs. You can use either the API signature or the certificate from the account holder's profile when you create the header. To manage API certificates, see Creating and Managing NVP/SOAP API Credentials.

The X-PAYPAL-AUTHORIZATION header contains

  • A timestamp
  • The access token from the GetAccessToken response
  • A signature generated from the following information:
    • Your API username
    • Your API password
    • The access token from the GetAccessToken response
    • The token secret from the GetAccessToken response
    • The endpoint for the PayPal API operation's request, such as https://api.paypal.com/nvp
    • The HTTPS delivery method, such as POST
    • Request parameters associated with the request

Note: You can use a certificate instead of the API username and API signature.

PayPal provides SDKs that you can use to generate authentication header signatures for Java, PHP, and .NET. When you use the SDK, you will get two values, such as the following:

Signature=tLWUfZU9Np/7qgPqWF1LMIWjY1s=
Timestamp=1285744515

Use the values to construct the header as follows:

X-PAYPAL-AUTHORIZATION=timestamp=1285744515,
token=5wZptMaHXQfihLKZFscuGjeKOPqQrlfHFPqRc1QlItX3vYi6,
signature=tLWUfZU9Np/7qgPqWF1LMIWjY1s=

Java Example

The PayPal Java SDK provides a method for creating the X-PAYPAL-AUTHORIZATION header. See the getAuthHeader method in the OauthSignature.java file of the com.paypal.sdk.util package in paypal_base.jar.

import java.util.Iterator;
import java.util.Map;

import com.paypal.sdk.util.OAuthSignature;
import com.paypal.sdk.util.OAuthSignature.HTTPMethod;

public class TestOauthSignature {

  private static String apiUserName = "..._biz_api1.gmail.com";
  private static String apiPassword = "1255077037";
  private static String accessToken = "2WhQDDM4...";
  private static String tokenSecret = "j0YhbTgcy.K5VjpQa7Ru8oM...";
  private static HTTPMethod httpMethod = OAuthSignature.HTTPMethod.POST;
  private static String scriptURI = "https://api.sandbox.paypal.com/nvp";
  private static Map queryParams = null;

  public static void main(String[] args) {
    try{
      Map map = OAuthSignature.getAuthHeader(apiUserName, apiPassword,
      accessToken, tokenSecret, httpMethod, scriptURI, queryParams);
      // Display Signature and Timestamp to console.
      Iterator itr = map.entrySet().iterator();
      while(itr.hasNext()){
        Map.Entry entry = (Map.Entry)itr.next();
        System.out.println(entry.getKey() + ": " + entry.getValue());
      }
    }catch (Exception e) {
      // handle exception
    }
  }
}

Granting Permission to Access Account Holder Information

After you have created an authentication header as described above, you can call GetBasicPersonalData and GetAdvancedPersonalData to obtain basic and advanced information about the account holder.

Basic information includes the following:

  • First Name
  • Last Name
  • Email
  • Full Name
  • Business Name
  • Country
  • PayerID

Advanced information includes the following:

  • Date of birth
  • Postcode
  • Street1
  • Street2
  • City
  • State
  • Phone

These two API calls work like all other APIs in PayPal — if you have permission, the call will succeed. If not, the call will fail. For both APIs, if the account holder has not given consent to access the requested data, the service will return an error indicating that you do not have permission to perform the action on behalf of another user.

The form of the call is as follows:

curl https://svcs.paypal.com/Permissions/GetBasicPersonalData \
  -s \
  --insecure \
  -H "X-PAYPAL-AUTHORIZATION: token=...,signature=..., timeStamp=..." \
  -H "X-PAYPAL-REQUEST-DATA-FORMAT:NV" \
  -H "X-PAYPAL-RESPONSE-DATA-FORMAT:NV" \
  -H "X-PAYPAL-APPLICATION-ID:APP-1JE4291016473214C" \
  -d attributeList.attribute(0)=http://axschema.org/contact/email \
  -d attributeList.attribute(1)=http://schema.openid.net/contact/fullname \
  -d requestEnvelope.errorLanguage=en_US
responseEnvelope.timestamp=2011-10-24T01%3A37%3A26.565-07%3A00&responseEnvelope.ack=Success&responseEnvelope.correlationId=5d8bf1913be02&responseEnvelope.build=2210301&response.personalData(0).personalDataKey=http%3A%2F%2Faxschema.org%2Fcontact%2Femail&response.personalData(0).personalDataValue=jdoe%40someisp.com&response.personalData(1).personalDataKey=http%3A%2F%2Fschema.openid.net%2Fcontact%2Ffullname&response.personalData(1).personalDataValue=John+Doe

Notes:

  1. The X-PAYPAL-AUTHORIZATION header was generated with URL "https://svcs.paypal.com/Permissions/GetBasicPersonalData".
  2. ACCESS_BASIC_PERSONAL_DATA and ACCESS_ADVANCED_PERSONAL_DATA access permissions have been previously granted to the API caller.
  3. This example illustrates use of the GetBasicPersonalData API. A request to GetAdvancedPersonalData would be the same except for the URI, and the response fields would differ.
  4. The URL used in curl and the URL used to generate X-PAYPAL-AUTHORIZATION must be identical.
Feedback