Permissions Service Getting Started Guide

Get up and running with the Permissions Service:

Overview

The PayPal Permissions Service enables your application to obtain the authorization needed to make PayPal API calls (and take action) on behalf of your customers who have PayPal accounts.

Key concepts

Using the Permissions Service, PayPal account holders can grant to your application the permission to make specific PayPal actions on their behalf. With a Permissions Service-enabled application, PayPal account holders (such as merchants and customers) need not set third-party permissions in their profile and then explicitly notify you of the various permissions they have granted. Instead, your web site or application can incorporate this task seamlessly with the operations in the Permissions Service API.

For example, suppose you provide a shopping cart application for merchants where your application makes calls to the Express Checkout API to complete payments made into merchant accounts. Here, your shopping cart application is a third party in transactions between PayPal and merchants, and therefore it requires permission from the merchants to take actions that affect their PayPal accounts. The Permissions Service API enables your application to request the permissions needed from the merchants in order for your application to execute the Express Checkout APIs on their behalf.

The interface exposed to your customers by the Permissions Service is automated and easy to use—it walks your customers through the different PayPal permissions, detailing what each grants. Permissions are organized in self-descriptive groups, which minimizes the time it takes your customers to grant the appropriate permissions. Once your customer finishes the permissions flow, they are redirected back to your site so they can complete any unfinished business started there.

The following diagram outlines the process flow used to incorporate the Permissions Service into your applications:

Permissions Service Process Flow

Figure 1. Permissions Service Process Flow

Make your first call

To make a call to the Permissions Service RequestPermissions operation, supply the necessary HTTP headers and call payload to the service endpoint.

A call to the RequestPermissions operation involves two users:

  • API Caller, represents your application and the account whose credentials the application uses to make the call
  • Receiver, the account granting the necessary permissions

The following steps outline the inputs needed to make the call.

  1. Obtain the endpoint for the environment and operation you are addressing.

    The Sandbox endpoint for the RequestPermissions operation is:

    https://svcs.sandbox.paypal.com/Permissions/RequestPermissions
    
  2. Format the HTTP headers needed to make the call.

    To call the RequestPermissions operation, supply the following HTTP headers:

     // Sandbox API credentials for the API Caller account
     X-PAYPAL-SECURITY-USERID : Sandbox-Caller-User-Id
     X-PAYPAL-SECURITY-PASSWORD : Sandbox-Caller-Password
     X-PAYPAL-SECURITY-SIGNATURE : Sandbox-Caller-Security-Signature
     
     // Sandbox Application ID
     X-PAYPAL-APPLICATION-ID : APP-80W284485P519543T
     
     // Input and output formats
     X-PAYPAL-REQUEST-DATA-FORMAT : JSON
     X-PAYPAL-RESPONSE-DATA-FORMAT : JSON
     
  3. Format the call payload.

    The RequestPermissions operation requires the following payload input fields, formatted here as a JSON object:

     {
     "scope":"EXPRESS_CHECKOUT",                        // List of permissions that need to be granted
     "callback":"https://example.com/success.html"  // The URL to where the user is redirected after granting permissions
     "requestEnvelope": {"errorLanguage":"en_US"},     // Language used to display errors
     }
     

    That's it, you're now set to make the call.

  4. Make the call.

  5. If the RequestPermissions call is successful (the ack field in the response contains Success), redirect the user to the PayPal permissions page so they can grant the appropriate permissions:

    1. Retrieve the token value from the response of the RequestPermissions call.

      Here is an example of a successful RequestPermissions response with the token highlighted:

       {
         "responseEnvelope": {
         "timestamp": "2011-08-20T15:12:20.833-07:00",   // GMT time that the server issued the response
         "ack": "Success",                               // Status of the response
         "correlationId": "nnnnnnnnnnnn",                // ID identifying the response
         "build": "nnnnnnn"                              // Version of the server
       },
         "token":"Your-Token"                             // Token used to access the PayPal Permissions page
       }
       
    2. Use the token value in an authorization redirect to PayPal using the following Sandbox URI:

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

      When you redirect your customer to the PayPal Permissions page, they are requested to grant the set of permissions specified in your request. The image below shows an example for the EXPRESS_CHECKIN permission:

      Permissions Service: Granting Permissions

      Figure 2. Granting Permissions

After granting the appropriate permissions, your customer is returned to the URL that you specified in the callback field, and PayPay returns to your application a verification code that you use in a follow-up call to the GetAccessToken operation. For complete details on how to gain access to the permissions your customer granted, refer to the Permissions Service Developer Guide.

Try it

The following cURL command contains a call to the RequestPermissions operation. Run the command by copying and pasting it into a code window. (If cURL is not installed on your system, you can download the free cURL executable from https://curl.haxx.se/download.html.)

curl https://svcs.sandbox.paypal.com/Permissions/RequestPermissions \
  -s \
  --insecure \
  -H "X-PAYPAL-SECURITY-USERID: caller_1312486258_biz_api1.gmail.com" \
  -H "X-PAYPAL-SECURITY-PASSWORD: 1312486294" \
  -H "X-PAYPAL-SECURITY-SIGNATURE: AbtI7HV1xB428VygBUcIhARzxch4AL65.T18CTeylixNNxDZUu0iO87e" \
  -H "X-PAYPAL-REQUEST-DATA-FORMAT: JSON" \
  -H "X-PAYPAL-RESPONSE-DATA-FORMAT: JSON" \
  -H "X-PAYPAL-APPLICATION-ID: APP-80W284485P519543T" \
  -d '{
      "scope":"EXPRESS_CHECKOUT", \
      "callback":"https://example.com/success.html", \
      "requestEnvelope": { \
        "errorLanguage":"en_US" \
      }}'

Voilà! You have made your first call to the Permissions Service.

After issuing the command, the Permissions Service should return a successful response.

The above call is made possible by the use of a publicly-available set of Sandbox credentials (highlighted in the call). To get a feel for working with the APIs, complete the entire transaction flow in the Sandbox by substituting your own Sandbox credentials and user accounts into the above command.

If your original call is not successful, review the call response for the error details and address the problem before resubmitting the call.

Next steps

To learn more about the Permissions Service:

  1. Set up a sandbox environment so you can make test calls with the Permissions Service. See Apps 101 for more information.
  2. Substitute your own Sandbox credentials in the above cURL command, then reissue the command to ensure you have correctly set up your Sandbox users. Note that the cURL example makes use of two users: an API Caller and a Receiver.
  3. Modify the inputs to the command to obtain permissions for different PayPal commands.
  4. See How to Request Third-Party Permissions Using the Permissions Service.
  5. Review the Permissions Service Developer Guide for a complete reference to each of the available operations, and their input and output fields.
  6. To get help with questions, discuss issues and share ideas, go to: