Permissions and Authentication Process

DOCSDEPRECATED

Last updated: Feb 27th, 7:31am

Important: PayPal Here is deprecated. PayPal doesn't accept new integrations but continues to support existing integrations.

Merchants must enable your application to process transactions on their behalf:

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, complete 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 processbefore 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:

1https://www.sandbox.paypal.com/signin/authorize?scope=openid 
2https://uri.paypal.com/services/paypalattributes/business 
3https://uri.paypal.com/services/paypalhere address 
4email 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.

To generate the proper tokens, follow these steps:

Follow the steps above to obtain the proper permissions and generate the authorization code. Remember, this code is only valid for three minutes.
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.

Choose your programming language:

cURL
PHP
Java

1curl -X POST https://api-m.sandbox.paypal.com/v1/identity/openidconnect/tokenservice
2-H 'Authorization: Basic Y2xpZW50SUQ6Y2xpZW50U2VjcmV0'
3-d 'grant_type=authorization_code&code={authorization_code}'

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:

1{
2  "token_type": "Bearer",
3  "expires_in": "28800",
4  "refresh_token": "<var>Refresh-Token-Value</var>"
5  "access_token": "<var>Access-Token-Value</var>"
6}

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: