Permissions and Authentication Process

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:

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 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:

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:

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.

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:

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:

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:

1curl -X POST https://api-m.sandbox.paypal.com/v1/identity/openidconnect/tokenservice
2  -H 'authorization: Basic Y2xpZW50SUQ6Y2xpZW50U2VjcmV0'
3  -H 'content-type: application/x-www-form-urlencoded'
4  -d 'grant_type=refresh_token&refresh_token={refresh_token}'

Request Parameters

Refresh Token Response JSON Object

1{
2  "token_type": "Bearer",
3  "expires_in": "28800",
4  "access_token": "<Access-Token>"
5}

Next

Configure a status check.