Connect with PayPal

Integrate

This section describes how to complete a basic Connect with PayPal integration in Sandbox. See LIPP flow for the links to use for an earlier LIPP integration.

To take your integration live, see 10. Go live.

1. Create the app

To get started, create a PayPal REST API application to receive the credentials you need to make API calls.

  1. Click Log into Dashboard and log in with your PayPal credentials.
  2. Click My Apps & Credentials.
  3. Under REST API apps, click Create App.
  4. Type a name for your app. Since your app name is shown on your customer consent page, we recommend that you use a customer-facing app name. Enter the App Name, then click Create App.

2. Enable Connect with PayPal

After you create an app, you must enable Connect with PayPal for that app in the dashboard:

  1. In the Sandbox App Settings section, enter the Return URL (redirect_uri) where your users are redirected after completing the Connect with PayPal flow. You must enter a URL before you can save the Connect with PayPal app settings.

  2. Select Connect with PayPal (formerly Log in with PayPal) and click Advanced Options:

    1. Select the information you want your users to share with you.

    2. Enter the URLs for your privacy policy and user agreement.

      Type Sample URL Description
      Privacy policy URL https://example.com For testing, you can enter https://example.com in the sandbox app settings.
      User agreement URL https://example.com For testing, you can enter https://example.com in the sandbox app settings.

      When you are ready to go live, replace these sandbox URLs with the live URLs. These are reviewed by our privacy and security team and are necessary for activating Connect with PayPal for your site.

  3. By default, PayPal requires users to first confirm their email account. Confirmed email indicates that the user's email is active. To allow customers who have not confirmed their emails with PayPal to use Connect with PayPal anyway, select Enable customers who have yet to confirm their email address with PayPal to log in to your app.

  4. Click Save. If you forgot to enter a return URL, the dashboard prompts you for one before you can save your settings.

Store Your Credentials

After you successfully create your PayPal application and enable Connect with PayPal, make note of your client ID which is also known as application ID and secret. You'll need these in the next steps as you build your button and call the Identity API.

3. App review

Before going Live, your app must be reviewed by PayPal to approve the sharing of customer data. Full name is enabled by default, but all other scopes require PayPal's approval through the app review process.

Note: The app review process typically takes 7-10 days, Be sure to initiate the app approval process at least 7-10 days before your planned Go Live date.

When you are ready to start the App review, send a request to help-loginappreview@paypal.com.

The request must include the following:

  • Client ID of your live app
  • Description of your app/site. Include screenshots or site URL and a short explanation of the app/site.
  • Detailed description of how your app will use the Connect with PayPal (formerly Log In with PayPal) feature.
  • List of the scope attributes you’d like to enable.
  • Description of how you will use each scope attribute, how it will benefit your users, and why the scope is needed for app's functionality.

4. Build the button

To build the button that your customers will click, you can generate a PayPal button or you can create your own button.

Generate a PayPal button

The simplest method is to enter your information into our Connect with PayPal Button Builder which generates JavaScript code that you embed on your website. With this option, you can easily customize the branded Connect with PayPal button and your authorization endpoint and parameters will be dynamically generated.

  1. Configure the button using the Connect with PayPal Button Builder.
  2. Embed the generated button code on your website.
  3. (Optional) Modify the generated javascript code.

Create your own button

If you'd prefer to create the Connect with PayPal button yourself, you can create your own button and then construct the authorization endpoint and parameters manually. You can either embed a PNG version of the branded Connect with PayPal button or create your own button image using PayPal's Button Design Guide.

  1. Decide whether to use the branded Connect with PayPal button or to create your own.

    • Branded Connect with PayPal button - Use the following URL for the button image location: https://www.paypalobjects.com/webstatic/en_US/developer/docs/login/connectwithpaypalbutton.png.

    Note: Do not download the button image and host it on your server. The button image might become out of sync with updates to the button image made by PayPal.

  2. Each time a user clicks the Connect with PayPal button the authorization URL is called. Construct the authorization endpoint according to the following template:

    https://www.sandbox.paypal.com/connect?flowEntry=static&client_id=[client id]&scope=[list of scopes]&redirect_uri=[return URL]
    
    Variable Description
    client ID Replace client id with your app’s sandbox or live client ID, depending where this URL is used.

    Example:

    ARfDleH_j-C17kxbdUzYivR70xP5Uy5N_DrFZVOvyZvNGBaPB_QNbwWkgF7lMsemGJycLRFVwaM
    list of scopes Replace list of scopes with a space-separated list of scopes. It is mandatory to include openid scope. See Scope attributes for details on how attributes map to scopes.

    Example:

    openid profile email address https://uri.paypal.com/services/paypalattributes
    return URL Page to return to after successful login. This URL must be encoded and exactly match the Return URL you set in the My App & Credentials page.

    Example:

    https%3A%2F%2Fwww.myreturnurl.com&state=123456

    Example of full URL:

     https://www.sandbox.paypal.com/connect/?flowEntry=static&client_id= ARfDleH_j-C17kxbdUzYivR70xP5Uy5N_DvNGBaPB_QNbwWkgF7lMsemGJycLRFVwaM&response_type=code&scope=openid profile email address&redirect_uri=https%3A%2F%2Fwww.myreturnurl.com&state=123456
    
  3. (Optional) Use the following advanced parameters to further customize your button functionality:

    Parameter Description
    response_type code – to receive authentication code in the response.
    id_token – used only by direct instruction of your integration team.
    fullPage To open the flow in a mini browser, do not pass this parameter.

    To open the Connect with PayPal flow as a full page in the same tab, pass true.

5. Get authorization code

If the customer successfully logs in to PayPal and consents to sharing basic information, PayPal passes an authorization code to the return URL you specified.

Parameter Description
authorization code The authorization code is appended as a parameter to the return URL after the user logs in and consents to share information with your website.

Example:

https://myreturnurl.com/?code={authorization_code}&scope=address%20openid%20profile%20email

6. Get access token

In this step, you exchange the authorization code for an access token to call PayPal's user profile service. The following diagram illustrates how the access token is used to receive user information.

access-token-flow

  1. Make a call to PayPal's tokenservice endpoint:

    https://api.sandbox.paypal.com/v1/oauth2/token

  2. Pass the authorization code to the tokenservice endpoint with the following parameters:

    Parameter Specify in Description
    Authorization header Separate your Base64-encoded client ID and secret credentials by a colon (:).
    grant_type form body Set to authorization_code.
    code form body

Sample Request

curl -X POST https://api.sandbox.paypal.com/v1/oauth2/token \
-H 'Authorization: Basic {Your Base64-encoded ClientID:Secret}=' \
-d 'grant_type=authorization_code&code={authorization_code}'

Response fields

Field Type Description
token_type: {type} String Defines the type of token, in this case the token type is Bearer.
expires_in: 28800 String Identifies the number of seconds until the access token expires. Default is 28800 seconds or 8 hours.
refresh_token: {refresh token} String Identifies the actual token used to refresh the access token.
access_token: {access token} String Identifies the actual token used to call the user info endpoint.

Sample Response

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

Note: The access token expires after a short period of time, so you'll also receive a refresh token that you will use to periodically refresh the access token. When you need to make a call to the user info service, use the refresh token first to get a new access token which you can then use to call the user info service.

7. Exchange refresh_token for access_token

  1. Make a call to Paypal's tokenservice endpoint:

    https://api.sandbox.paypal.com/v1/oauth2/token

  2. Pass the refresh token to the tokenservice endpoint with the following parameters:

    Parameter Specify in Description
    Authorization header Separate your Base64-encoded client ID and secret credentials by a colon (:).
    grant_type form body Set to refresh_token.

    Sample request

    curl -X POST https://api.sandbox.paypal.com/v1/oauth2/token \
    -H 'Authorization: Basic {Your Base64-encoded ClientID:Secret}=' \
    -d 'grant_type=refresh_token&refresh_token={refresh token}'
    

Response fields

Field Type Description
token_type: {type} String Defines the type of token, in this case the token type is Bearer.
expires_in: 28800 String Identifies the number of seconds until the access token expires. Default is 28800 seconds or 8 hours.
access_token: {access token} String Identifies the actual token used to call the user info endpoint.

Sample response

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

8. Get customer info

Now that you have the access token, call the Show user profile information method with the desired parameters to obtain the customer information.

9. Test the integration

To test your integration, complete these steps.

  1. Log in to the developer dashboard and create a new sandbox test account.
  2. Click your Connect with PayPal button.
  3. Log in to PayPal using the test buyer account you created.
  4. Make sure you received a non-empty authorization code in the return URL query parameter.
  5. Exchange the auth code for a token as described in 6. Get Access Token.
  6. Call the user info endpoint with the access token and verify that you received the correct user information.

When your test is complete and you're satisfied with the results, you can launch your new button into production.

10. Go live

Once your app has been approved to go live, you just need to replace the sandbox endpoints with the live endpoints.

Note: Before going live, PayPal must review your app to approve the sharing of customer data. To send your app for review, login to the PayPal Dashboard and follow the instructions at My App & Credentials. The app review process takes 7-10 business days. You will be able to call the user info endpoint to receive customer information only after you have received email confirmation from the app review team.

To launch your button into production, complete these steps:

Replace sandbox credentials with live credentials

  1. Button URL: change the endpoint from https://www.sandbox.paypal.com/connect? to https://www.paypal.com/connect?

    Example

    https://www.paypal.com/connect?flowEntry=static&client_id= ARfDleH_j-C17kxbdUzYivR70xP5Uy5N_DvNGBaPB_QNbwWkgF7lMsemGJycLRFVwaM&response_type=code&scope=openid%20profile%20email%20address&redirect_uri=https%3A%2F%2Fwww.google.com%3Fstate=123456
    
  2. Code to token: change the endpoint from https://api.sandbox.paypal.com/v1/oauth2/token to https://api.paypal.com/v1/oauth2/token

  3. User info: change the endpoint from https://api.sandbox.paypal.com/v1/identity/oauth2/userinfo to https://api.paypal.com/v1/identity/oauth2/userinfo

Test a live user flow

  1. Click your Connect with PayPal button.
  2. Log in to the PayPal window using a real buyer account. If you don’t have a real PayPal buyer account, go to the PayPal website and click Sign Up.
  3. Click on the Connect button to complete the consent.
  4. Make sure you received a non-empty authorization code in the return URL query parameter.
  5. Exchange the auth code to token as described in 6. Get Access Token.
  6. Call the user info endpoint with the access token and verify that you receive the correct user information.

Next

Best Practices

Feedback