Initiating the PayPal onboarding flow

When a merchant logs in to your back-office site, display a button that initiates the PayPal Here onboarding flow. When a merchant initiates the onboarding flow, redirect the merchant to a PayPal web page in a separate browser or an embedded view. The PayPal flow leads the merchant through the steps to configure their Business account for PayPal Here processing.

To onboard your merchants, use this flow:

  1. Initiate the permissions flow to have the merchant provide the ability for you to process on their behalf. Once the permissions are granted, PayPal will redirect them back to your site. If the merchant doesn't have a PayPal account yet, they'll be able to create one during this step.
  2. After the merchant returns to your site, do a status check to see if they have PayPal Here enabled on their account.
  3. If the merchant has a PayPal Here-enabled account, you're all set. If not, initiate the signup flow to enable the product on their PayPal business account.

Permissions flow

After the merchant grants you permission to act on his or her behalf, your app handles transactions and the funds go into the merchant's PayPal account. You receive merchant permissions as an authorization code.

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&response_type=code&redirect_uri={redirectUri}&client_id={client_id}

In the redirect URL, specify these parameters:

  • 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 to the page to which you redirect the merchant so that he or she can grant you permission to process payments on the merchant's behalf. When the merchant clicks Agree, PayPal generates an authorization code. Retrieve this code from the query string and use it to make calls to get the refresh and access tokens.
  • 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. Also, the domain must be an SSL-enabled domain. For example, https://example.com.

The following sample for the fictitious DocTest app shows a consent page that the merchant sees when he or she grants permissions::

When the merchant clicks Agree, your app redirects him or her to the redirect_uri that you specified when you directed them to PayPal to grant permissions. PayPal appends an authorization code to the URL. On the return URL page, you generate the refresh and access tokens from the authorization code.

Generate 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. The following call also generates an initial access token, which you can use in your requests to the PayPal Here APIs:

curl -X POST https://api.sandbox.paypal.com/v1/identity/openidconnect/tokenservice \
  -H 'Authorization: Basic QWRhYlZDRkdYQkhrQUw4b3ZfcGlQcWo2Z01hZjRldzZDQVRKYUxTYzRQT25qTFh5WlB3NHhzZzQ3RnNLZDhZMi00dGthTWVFZFdHMl9ETUs6RU96SjQ2MFlGV0xTVTlQckk2XzhLTFB6UnF4a0dfWElCX09ZbjFwZ1lHSVBTTU1GVVJfanRDcHlaX2tVSkNUVi15ZTAzdS1ac3k0RjNlY1U=' \
  -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 QWRhYlZDRkdYQkhrQUw4b3ZfcGlQcWo2Z01hZjRldzZDQVRKYUxTYzRQT25qTFh5WlB3NHhzZzQ3RnNLZDhZMi00dGthTWVFZFdHMl9ETUs6RU96SjQ2MFlGV0xTVTlQckk2XzhLTFB6UnF4a0dfWElCX09ZbjFwZ1lHSVBTTU1GVVJfanRDcHlaX2tVSkNUVi15ZTAzdS1ac3k0RjNlY1U="
  ),
));

$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 QWRhYlZDRkdYQkhrQUw4b3ZfcGlQcWo2Z01hZjRldzZDQVRKYUxTYzRQT25qTFh5WlB3NHhzZzQ3RnNLZDhZMi00dGthTWVFZFdHMl9ETUs6RU96SjQ2MFlGV0xTVTlQckk2XzhLTFB6UnF4a0dfWElCX09ZbjFwZ1lHSVBTTU1GVVJfanRDcHlaX2tVSkNUVi15ZTAzdS1ac3k0RjNlY1U=")
  .build();

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

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

  • Authorization request header. The Base64-encoded client ID and secret credentials separated by a colon (:).
  • grant_type. The type of credential 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": "Refresh-Token-Value"
  "access_token": "Access-Token-Value"
}

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.

The roles of the refresh and access tokens are explained further on the Token Management page.

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

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.

Status check

The merchant uses the signup flow to add the PayPal Here product to his or her account to process transactions. Before you send the merchant through this flow, complete a status check to determine whether the merchant has already enabled PayPal Here. To complete this check, take the access token that you generated previously and call the /status endpoint.

curl -X GET https://api.sandbox.paypal.com/retail/merchant/v1/status \
  -H 'authorization: Bearer {Access-Token_of_merchant}' \
  -H 'content-type: application/json'
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.sandbox.paypal.com/retail/merchant/v1/status",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "authorization: Bearer {Access-Token_of_merchant}",
    "content-type: application/json"
  ),
));

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

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

Request request = new Request.Builder()
  .url("https://api.sandbox.paypal.com/retail/merchant/v1/status")
  .get()
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Bearer {Access-Token_of_merchant}")
  .build();

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

Response from the call to the /status endpoint:

{
  "status": "ready",
  "paymentTypes": [
    "tab",
    "key",
    "card"
  ],
  ....
}

A successful request returns a response that includes a status field, paymentTypes object, and other fields. Make sure that the status is ready and the paymentTypes object includes either card for the US or chip for the UK and AU. The combination of those values in the response indicates that your merchant has enabled PayPal Here on their business account and is ready for processing. If the status is not ready or the payment types of card or chip are not present, you must send the merchant through the signup flow for their respective region.

PayPal Here signup flow

After you complete a status check and you determine that the merchant must enable PayPal Here on their account, you must send the merchant through the signup flow. This flow differs by region:

United States

For the US, you can either submit a HTML form post, or you can simply do a redirect and append the various query parameters. An example form post with the minimum requirements is:

<form method="post" name="pphsignup_form" action="https://www.paypal.com/signup-pph">
  <input type="hidden" name="partnertype" value="sdk">
  <input type="hidden" name="partner_id" value="{My-Bn-Code-Id}">
  <input type="hidden" name="partner_name" value="{SDK-Partner-Id}">
  <input type="hidden" name="swiper" value="n">
  <input type="submit" name="submit" value="Sign Up for PPH">
</form>

PayPal supports these request parameters:

Parameter Description Valid value
partnertype Required. The partner type. SDK.
partner_id Optional. An ID for the partner who built the code for the button that the merchant clicked. Obtain a BN code from your PayPal account manager. 32 characters.
partner_name Optional. Partner name to use for co-branding and reference purposes in the PayPal onboarding flow. If you pass a logourl, the logo overrides the partner name. 60 characters.
returnurl Required. The URL-encoded value to the page to which to return the merchant after he or she completes the signup flow. 1024 characters.
swiper Optional. Default is n. Enables the merchant to purchase a swiper as part of the onboarding flow. y- The merchant can order a PayPal Here triangle swiper.
n- Suppresses the option to order the PayPal Here swiper. Use this option if you issue your own swipers OR for merchants who do not intend to use the PayPal swiper. Default is n.
first_name The merchant's first name. 32 characters.
last_name The merchant's last name. 32 characters.
email The merchant's email address. 127 characters.
business_name The merchant's business name. 60 characters.
business_phone The merchant's business phone number. 10 digits.
business_address1 The merchant's business address line 1. 100 characters.
business_address2 The merchant's business address line 2. 100 characters.
business_city The merchant's business address city. 40 characters.
business_state The merchant's business address state. 2 characters.
business_zip The merchant's business address zip. 5 digits.
logourl An HTTPS URL pointing to the logo of your location. Must be HTTPS.

About the submittal form

Your system stores and you can use certain merchant information to pre-populate the form. PayPal recommends you populate as many merchant information fields as possible including first name, last name, email, business name, business address, and phone. Note these guidelines:

  • Your system can supply any, all, or none of the merchant's information in the submitted form.
  • The merchant can edit his or her information during the onboarding flow.
  • The onboarding flow silently drops and does not generate errors for any incorrect information that the system provides.
  • Information associated with an existing PayPal account takes precedence over information submitted by your system.
  • Do not populate the home_address1 and home_address2 fields with the account owner's address information or mobile phone number. PayPal uses these fields for customer identity verification and misinformation can result in decline.

When you submit a business logo, follow the PayPal Cobranding Guidelines. Also, consider how the logo appears next to the PayPal logo. Also, follow these logo guidelines:

Logo_Property Description
Height 66 pixels max height.
Width 310 pixels max width.
Background Transparent background (the artwork is placed on a background of #F5F5F5).
Resolution 72 DPI minimum.
File Format PNG with transparency. If you are using JPG or GIF, use a #F5F5F5 background.
Color Format RBG.
Policies Submit artwork that you can legally share. The artwork must represent your company logo. Do not include additional imagery, background colors, or words. Artwork appears next to the PayPal logo and both logos must have equal prominence.

Note: To promote your brand in the best light possible, PayPal does not use artwork that does not meet our guidelines or our presentation standards.

This image provides a guideline for your logo sizing and image placement:

If you have questions on these guidelines, contact your PayPal account representative.

Return the merchant to your site

After the merchant completes the signup flow, your app returns them to the URL that you specified in your original redirect (the returnurl parameter). When PayPal redirects the merchant back to your site, PayPal returns a status code that indicates the status of the merchant's PayPal Here account setting.

The status code has two levels:

  • The first level indicates success, pending, or failure.
  • The second-level, a sub-code, contains a more detailed description of the status.
Return Status Subcode
success approved
pending manualreview
failure Either declined or error

For example:

https://example.com/paypal?status=success&subcode=approved

United Kingdom and Australia

For UK and AU, you cannot pre-fill the merchant's information. Also, the flow does not include a way to return the merchant to your site after signup. Instead, provide a provide a signup button and change this to a check status button after the merchant is directed to the signup URL.

Also, provide some verbiage on your site that explains that merchants must return to your site and click check status to finalize the connection. This button completes the status check as outlined previously to determine whether PayPal Here was enabled on the merchant's business account. If it is enabled, display a congratulatory message and instruct the merchant that they are ready to process. If it is not enabled yet, notify the merchant to call PayPal Customer Support to enquire about the status of their PayPal Here application.

To direct UK merchants to sign up for PayPal Here:

https://www.paypal.com/webapps/mobilemerchant/page/mpa/ob/geturl?onbver=2.0&country.x=GB&hs=login

To direct AU merchants to sign up for PayPal Here:

https://apply.paypal-apac.com/here/au/Step1A.aspx