Permissions and Authentication Process

Merchants need to allow your application to process transactions on their behalf. The steps in the process are as follows:

Step Description
1. Direct the merchant to the authentication PayPal URL Facilitates the authentication process.
2. Host a page to which PayPal can automatically redirect the merchant with an authorization code. You will retrieve the permissions from PayPal as an authorization code that is valid for three minutes.
3. Use the authorization code to generate refresh and access tokens. See also:
- Using the sample server
- Manually generating refresh and access tokens

After completing the permissions flow, perform a Status Check to make sure the merchant is ready to process PayPal Here transactions.

Note: It may be necessary to send the merchant through the business account registration process before they are able to process PayPal Here transactions.

Authentication token policies

To ensure that the merchant is protected on payments that use PayPal Here requests, you must adhere to these policies:

Do not store credentials or tokens locally in your apps. Instead, store credentials and tokens in a secure location in your data center. Cache credentials and tokens needed to make API calls in your application.

Permissions for transaction processing

To get the merchant permissions for your app, direct the merchant to this PayPal URL. This example uses the sandbox endpoint:

https://www.sandbox.paypal.com/signin/authorize?scope=openid https://uri.paypal.com/services/paypalattributes/business https://uri.paypal.com/services/paypalhere address email profile&response_type=code&redirect_uri={redirectUri}&client_id={client_id}

In the redirect URL, specify these parameters:

Parameter Description
scope The scopes for managing payments and using PayPal Here. Specify all scopes listed in the previous example. Separate scopes with a space. For information about other scopes, see the Log In with PayPal documentation.
response_type The response type. Set to code.
redirect_uri The URI of the page to which PayPal will redirect the merchant after they have granted you permission to process transactions on their behalf. See the Generating Refresh and Access Codes from the Authorization Code below for a more in-depth explanation.
client_id The PayPal-assigned client ID for your app. Be sure to use the client ID for the correct environment (sandbox or live).

Note: The redirect_uri domain must match the return URL domain that you provided on the Developer website when you created your REST app, and it must be an SSL-enabled domain; for example, https://example.com.

Example agreement page

The following sample for the fictitious DocTest app shows a consent page that the merchant sees when they grant permissions:

When the merchant clicks Agree, PayPal redirects them to the redirect_uri specified in the steps above. PayPal appends an authorization code to the URL which is valid for only three minutes.

Authentication tokens

Using the sample server

In order to handle the token management process, there needs to be an available server. You can use your own server if you have already implemented one, or you could deploy our sample server. The sample server is written in Node.js and can either be deployed to your own Node server or you can use individual modules as you see fit.

Manual token management

If you'd like to handle this token management on your own, you can generate an access token from a refresh token and pass that into the SDK directly.

In order to generate the proper tokens, follow these steps:

  1. Follow the steps above to obtain the proper permissions and generate the authorization code. Remember, this code is only valid for three minutes.
  2. Use that authorization code to generate refresh and access tokens.

Generating refresh and access tokens from the authorization code

The authorization code, which is returned as code, is valid for only three minutes. You must use this code to generate the refresh token for the merchant’s app. This only needs to be done once, unless the merchant revokes permission.

The following call generates an initial access token, which you can use in your requests to the PayPal Here SDK.

curl -X POST https://api.sandbox.paypal.com/v1/identity/openidconnect/tokenservice \
  -H 'Authorization: Basic Y2xpZW50SUQ6Y2xpZW50U2VjcmV0' \
  -d 'grant_type=authorization_code&code={authorization_code}'
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.sandbox.paypal.com/v1/identity/openidconnect/tokenservice",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "grant_type=authorization_code&code={authorization_code}",
  CURLOPT_HTTPHEADER => array(
    "authorization: Basic Y2xpZW50SUQ6Y2xpZW50U2VjcmV0"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType, "grant_type=authorization_code&code={authorization_code}");
Request request = new Request.Builder()
  .url("https://api.sandbox.paypal.com/v1/identity/openidconnect/tokenservice")
  .post(body)
  .addHeader("content-type", "application/x-www-form-urlencoded")
  .addHeader("authorization", "Basic Y2xpZW50SUQ6Y2xpZW50U2VjcmV0")
  .build();

Response response = client.newCall(request).execute();

Provide an authorization header, grant type, and code in the request:

Parameter Description
Authorization request header The Base64-encoded client ID and secret credentials separated by a colon (:). Use the partner's credentials.
grant_type The type of credentials that you provide to obtain a refresh token. Set to authorization_code.
code The PayPal-generated authorization code.

Your refresh token POST request returns this JSON object:

{
  "token_type": "Bearer",
  "expires_in": "28800",
  "refresh_token": ""
  "access_token": ""
}

The response fields are:

Field Type Description
"token_type": "Bearer" String The token type, which is Bearer.
"expires_in": "28800" Integer The number of seconds until the access token expires. Default is 28800.
"refresh_token": "Refresh-Token-Value" String The refresh token.
"access_token": "Access-Token-Value" String The access token.

Important: PayPal Here tokens become inactive if the merchant revokes their third-party permissions from your app through the PayPal website.

Refresh tokens

Refresh tokens have the following characteristics:

  • Stored in a secure, persistent data store on your server and assigned to individual merchants.
  • Used to generate the access tokens required to complete payments and other back-office operations.
  • Do not expire.
  • Maximum length of 1024 characters.

Access tokens

Access tokens have the following characteristics:

  • Maximum length of 1024 characters.
  • Valid for 8 hours.
  • Should be used as a runtime variable.
  • Should be stored in a short-term program cache or equivalent.
  • Needs to be refreshed; this can be done just before or any time after expiry.

If all of the necessary information is provided into the SDK when initializing the merchant, then the SDK will automatically reach out to your server to initiate the generation of a new access token via the refresh URL that you provide. When you use your own refresh URL without the aid of the sample server, configure it so that it returns the token response directly without any modifications; this way the SDK is able to utilize the necessary information.

Generating an access token

This example call shows you how to use a refresh token to generate an access token:

curl -X POST https://api.sandbox.paypal.com/v1/identity/openidconnect/tokenservice \
  -H 'authorization: Basic Y2xpZW50SUQ6Y2xpZW50U2VjcmV0' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'grant_type=refresh_token&refresh_token={refresh_token}'
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.sandbox.paypal.com/v1/identity/openidconnect/tokenservice",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "grant_type=refresh_token&refresh_token={refresh_token}",
  CURLOPT_HTTPHEADER => array(
    "authorization: Basic Y2xpZW50SUQ6Y2xpZW50U2VjcmV0",
    "content-type: application/x-www-form-urlencoded"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType, "grant_type=refresh_token&refresh_token={refresh_token}");
Request request = new Request.Builder()
  .url("https://api.sandbox.paypal.com/v1/identity/openidconnect/tokenservice")
  .post(body)
  .addHeader("authorization", "Basic Y2xpZW50SUQ6Y2xpZW50U2VjcmV0")
  .addHeader("content-type", "application/x-www-form-urlencoded")
  .build();

Response response = client.newCall(request).execute();

Request Parameters

Parameter Description
Authorization request header Contains the Base64-encoded client ID and secret credentials separated by a colon (:). Use the partner's credentials.
grant_type The grant type for obtaining the access token. Set to refresh_token.
refresh_token The refresh token for the merchant.

Refresh Token Response JSON Object

{
  "token_type": "Bearer",
  "expires_in": "28800",
  "access_token": ""
}

Next

Feedback