Token management

When you work with the PayPal Here SDK, you manage these token types:

To handle the exchange of these tokens between your server and client, use a mid-tier service.

To deploy a mid-tier service, you can use the Authentication for the Retail SDK service, which is written in Node.js. With that sample server, you can simply deploy it directly and input your own required environment variables, or you can use individual modules as you see fit. This sample server generates and utilizes the SDK Composite Token.

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

The route you choose to authenticate determines the merchant's initialization method within the SDK. These authentication methods are discussed further in the SDK documentation.

Refresh tokens

Your app stores refresh tokens in a secure, persistent data store and assigns them to individual merchants. Your app uses merchants' refresh tokens to generate the access tokens required to complete payments and other back-office operations. These tokens do not expire. A token has a maximum length of 1024 characters. 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 QVN1eEEtWV9BNGloY21wNWNraTh4YlFBUnBvcUlGbUVEV1BnWmt5cWZqOUJyQXcxd0wyTFpaUTl1cnhFdVprbU0zQU1lY3ZJLXZleTdUVUE6RUdTdVl2ZFpfcUIwQ1UxTXZqRk0ybk5nbjJMaXRfMzhaQnE5ZUFGTS1wb1pycnlaT0dVU2haOWFSMHZ3WjdSTDM0N0w0VUZVNkQteVpuazA=' \
  -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 QVN1eEEtWV9BNGloY21wNWNraTh4YlFBUnBvcUlGbUVEV1BnWmt5cWZqOUJyQXcxd0wyTFpaUTl1cnhFdVprbU0zQU1lY3ZJLXZleTdUVUE6RUdTdVl2ZFpfcUIwQ1UxTXZqRk0ybk5nbjJMaXRfMzhaQnE5ZUFGTS1wb1pycnlaT0dVU2haOWFSMHZ3WjdSTDM0N0w0VUZVNkQteVpuazA=",
    "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 QVN1eEEtWV9BNGloY21wNWNraTh4YlFBUnBvcUlGbUVEV1BnWmt5cWZqOUJyQXcxd0wyTFpaUTl1cnhFdVprbU0zQU1lY3ZJLXZleTdUVUE6RUdTdVl2ZFpfcUIwQ1UxTXZqRk0ybk5nbjJMaXRfMzhaQnE5ZUFGTS1wb1pycnlaT0dVU2haOWFSMHZ3WjdSTDM0N0w0VUZVNkQteVpuazA=")
  .addHeader("content-type", "application/x-www-form-urlencoded")
  .build();

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

In this request, include these parameters:

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

Your refresh token POST request returns this JSON object:

{
  "token_type": "Bearer",
  "expires_in": "28800",
  "access_token": "Access-Token-Value"
}

Access tokens

Access tokens are a maximum of 1024 bytes in length and are valid for 8 hours (28800 seconds). The access_token value should be used as a runtime variable. If necessary, store the value in a short-term program cache or equivalent. Once an access token is expired, or about to be expired, you will need to refresh it using the above request. 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. This is done via the refresh URL that you would provide. When you use your own refresh URL, without the aid of the sample server, you'll want to configure it so that it simply returns the token response (above) directly without any modifications. This way the SDK is able to utilize the necessary information.

SDK composite tokens

A SDK Composite Token is a combination of the environment and a base64 encoded version of the access token, expiry, and refresh URL. The environment and the base64 encoded information are separated by a colon (:). This would be an alternative to using the access token, expiry, and refresh URL as separate parameters to pass into the SDK. This is the recommended way to initialize a merchant because everything is all inclusive within a single token and not sent as individual parameters. Also, if you're using the sample server (or any of it's modules), this is the token that's generated from that codebase. Samples of a SDK Compsite Token, and a decoded version, are below.

The SDK Compisite Token has a format of: {environment}:{base64 encoded combination of access token, expiry, and refresh URL}

live:WyJBMjNBQUdDM3dvWHRhaXRMOTB4NHFZUDczS0VieWJtX0hIMTIzNDVUb3hwTEFDZFhZb3Jfenl5YXhJeVctS3paNnBHOHR2QW56eXRhVmdWZzlDRzBLUXVrYXFRQk1EX2N3IiwiMjg4MDAiLCJodHRwOi8vZXhhbXBsZWRvbWFpbi5jb20vcmVmcmVzaD9tZXJjaGFudElEPTEyMyJd

The decoded value of the above is:

["A23AAGC3woXtaitL90x4qYP73KEbybm_HH12345ToxpLACdXYor_zyyaxIyW-KzZ6pG8tvAnzytaVgVg9CG0KQukaqQBMD_cw","28800","http://exampledomain.com/refresh?merchantID=123"]

After it's decoded, you can see that the first parameter is the access_token, followed by the expiry and the refresh URL. The refresh URL will be the link to your server that will handle the refreshing of the access_token. This will need to contain an identifier for your system to tell which merchant/refresh token to use to generate the new access token. If you are doing this with your own server, and not the sample server, then you'll need to encode these values on your own. Otherwise, with the sample server, this refresh URL will be generated automatically. The sample server uses an encrypted version of the refresh_token automatically instead of a merchant identifier and that process is explained further in the sample server documentation.