PayPal Link Integration Guide

This guide shows partners how to create and set up PayPal accounts for customers so that they can use their cards to fund PayPal transactions.

Integration steps

Set up your development environment

Before you can integrate Address Normalizer, you must set up your development environment. After you get a token that lets you access protected REST API resources, you create sandbox accounts to test your web and mobile apps. For details, see Get started.

Then, return to this page to integrate Address Normalizer.

Onboard an account

After you make your first call, get your client ID, and the PayPal integration team provisions that client ID, use your access token in the header of the call to v1/customer/consumer-referrals.

Endpoints

• Live: https://api-m.sandbox.paypal.com/v1/customer/consumer-referrals
• Test/Sandbox: https://api-m.paypal.com/v1/customer/consumer-referrals

Sample request

The following example request creates a consumer-referral resource for a customer with a credit card:

1POST https://api-m.sandbox.paypal.com/v1/customer/consumer-referrals
2
3Headers:
4Accept: application/json
5Content-Type: application/json
6Authorization: Bearer A015BWrB7LIoTRkFaYe...9Nhohl0eM1cvub82UzIn
7
8Body:
9{
10  "person_details": {
11    "names": [{
12      "given_name": "John",
13      "surname": "Doe"
14    }],
15    "phone_contacts": [{
16      "phone": {
17        "country_code": "1",
18        "national_number": "4025555555"
19      },
20      "phone_type": "HOME"
21    }],
22    "addresses": [{
23      "address": {
24        "line1": "1234 Main St",
25        "line2": "",
26        "city": "San Jose",
27        "state": "CA",
28        "country_code": "US",
29        "postal_code": "95131"
30      }
31    }],
32    "email_addresses": [{
33      "email_address": "user@partner.com",
34      "primary": true,
35      "confirmed": false
36    }]
37  },
38  "paypal_account_properties": {
39    "account_country_code": "US"
40  },
41  "financial_instruments": {
42    "card_accounts": [{
43      "account_number": "4xxx017406993726",
44      "type": "VISA",
45      "expiry_month": "11",
46      "expiry_year": "2018",
47      "country_code": "US",
48      "confirmation": {
49        "status": "CONFIRMED"
50      }
51    }]
52  }
53}

Sample response

The response contains person_details, along with the following additional information:

1{
2  "referral_id": "PD94bWw...dF9EXZWx",
3  "person_details": {
4    "names": [...],
5    "phone_contacts": [...],
6    "addresses": [...],
7    "email_addresses": [...]
8  },
9  "links": [{
10    "rel": "action_url",
11    "href": "https://www.sandbox.paypal.com/consumeronboarding/entry?referralid=PD94bWw...dF9EXZWx",
12    "method": "GET"
13  }]
14}

Manage the onboarding flow

To keep customers within the context of your website, you should present the onboarding flow in a new browser window that overlays the originating window, if possible. PayPal provides an optional JavaScript library that opens and manages the flow window, as well as indicating the ongoing activity, by overlaying the originating page. The library returns to full-page redirects where necessary, for example, on mobile devices.

Integrate this library as follows:

1<form method="POST" action="https://www.sandbox.paypal.com/consumeronboarding/entry">
2  <input type="hidden" name="referralid" value="QUFFVDV4UlFucGRFaVI3MFpNTlhoTUtIVTZiOXdxNU4vbFV2TXFKTXJIaVBjT3BzaHllRTRvWXRLSzA2TnNyRw" />
3  <input type="hidden" name="scope" value="https://uri.paypal.com/services/paypalattributes https://uri.paypal.com/services/wallet/card-accounts/external-update https://uri.paypal.com/services/wallet/card-accounts/read https://uri.paypal.com/services/wallet/card-accounts/partner-update" />
4  <input type="hidden" name="state" value="key1=value1;key2=value2" />
5  <input type="hidden" name="paypal_client_metadata_id" value="<passed in from Magnes SDK>" />
6  <input type="hidden" name="redirect_uri" value="https://www.somereturnurl.com/return" />
7  <button type="submit" id="start_onboarding_flow">Start Onboarding Flow</button>
8</form>

Handle return results

After completing the onboarding flow, the customer is redirected to the return URL, as specified for the REST App in the PayPal Developer Dashboard.

The return URL indicates the result of the onboarding flow. Depending on the flow outcome, the following parameters are returned:

• If onboarding succeeded, the code parameter contains an OAuth authorization code that is valid for only three minutes.
  1code=C101.Syt5P_nbtpeImhNl-C2...bYzUfkEWMMmn2Uwtx7njonIkbKn

  PayPal Link and adding the customer's cards that are selected are separate actions. A customer can link their PayPal account to the partner while some or none of their requested cards are added to their PayPal wallet. This scenario might occur when the customer has exceeded the card limit in their wallet while giving the partner the requested permission.

  PayPal recommends that partners run a call against each selected card to verify the card is linked to the customer's PayPal wallet.

• If an error occurs during the onboarding flow, the customer signs in and gets a consent denied error.
  1error_description=CONSENT%20DENIED&error=access_deniedn

  PayPal Link and the addition of the customer's cards that are selected are separate actions. A customer can add partner-issued cards to their PayPal wallet without agreeing to give the partner permissions through linking. For example, suppose that a customer initiates the PayPal Link flow, chooses one or more cards to add to their PayPal wallet, logs in and creates an account, then selects Not Now when prompted to grant consent to the partner. PayPal might have added the cards to the customer's PayPal wallet.

  Therefore, to prevent errors, PayPal recommends sending the customer a message notification that their PayPal account has not been linked with the partner.

Pass state information to the return URL

You can use the state parameter to pass information through the flow to the return point. This parameter must consist of key-value pairs encoded as query strings. For example, when passing the parameter myParam with value xyz and another parameter, myURL, with value https://localhost/linked-accounts/, the received state parameter is myParam=xyz&myURL=https%3A%2F%2Flocalhost%2Flinked-accounts%2F.

The state parameter is included as a URL parameter when the customer is redirected to the specified return URL at the end of the flow. You can amend the content of the state parameter with additional keys that contain information about the flow result, for example, error details.

Return URL errors

PayPal generally handles most errors internally. However, in some situations, PayPal might return the customer back to the merchant's redirect_uri with an error_description and/or error parameters. See Return URL errors for errors that might occur.

Get a consumer refresh token

PayPal's onboarding flows (for example, Log In with PayPal and Partner-Referred Consumer Onboarding) return an authorization code that corresponds to a set of permissions for accessing the customer's data. The short-lived authorization code has to be exchanged for a long-lived user refresh token. The typical lifetime is 10 years.

You must store the returned user refresh token securely with the partner's customer data.

The authorization code exchange and refresh token exchange are combined into the same section. See the HTTP status error codes table for error responses.

When doing an HTTP POST for an access_token or refresh_token, or for a new access_token using the refresh_token, the partner must pass in the Authorization: Basic <value> header and add the Base64 encoded string of your client ID and secret, separated by a colon as the <value>. For example:

1Base64(testClientId1234:testSecret1234) => dGVzdENsaWVudElkMTIzNDp0ZXN0U2VjcmV0MTIzNA==
2-H "Authorization: Basic dGVzdENsaWVudElkMTIzNDp0ZXN0U2VjcmV0MTIzNA==" \

Handle errors

See HTTP status codes to read about authorization code and refresh token exchange errors.

Sample refresh token response (consent revoked) - any attempts to complete API calls with missing customer consent fails and results in a 401 HTTP status with an invalid_refresh_token error:

1Status 401
2{
3  "error": "invalid_refresh_token",
4  "error_description": "No consent were granted"
5}

See HTTP Status error codes for HTTP errors that might occur.

Add a card account

You can create a card account and link that account to PayPal. A card account is an external credit, debit, or other card account, such as a gift card.

A card account must support real-time authorization, which enables PayPal to guarantee the funds with the payment. This guarantee must be possible without involving a card holder on a browser. This implies a pull model for money movement.

The Card Accounts API enables partners to add new cards or update existing cards in a linked PayPal wallet. PayPal must collect customer permission when initially linking the account.

Check card status

To optionally check if a card account exists, specify the card number or payment token for tokenized credit card in the URI. This call determines whether the card is already linked to a PayPal customer:

1curl -v -X POST https://api-m.sandbox.paypal.com/v1/wallet/check-card-account-exists \
2  -H "Content-Type: application/json" \
3  -H "Authorization: Bearer

A successful request returns the HTTP 200 OK status code with a JSON response that indicates whether the card account exists. Generally, merchants receive an indication of either true or false. However, sometimes PayPal might need to return a general REST error.

1{
2  "result": true,
3  "id": "CC-WQLBSG6JFP3QY"
4}

1{
2  "result": false
3}

Get data from consented users

Once you have the access token from the Consumer Refresh Token API, you can use the Get User Data API to pull information from consenting users. This information includes their email, PayPal ID, verified account status, and data that may be in your company's user consent contract.

Endpoints for Get User Data API

Request headers

Sample request

1curl GET https://api-m.sandbox.paypal.com/v1/oauth2/token/userinfo
2-H "Authorization: Bearer A23AAGy_1uaiD7pDP1t0GpYNXN-oO6lmGbec_8YsDexd4INtUFsz452pj8CxS5QPPZ874q3qlYvE80o9lrz-_K84Of5DEBAbA"
3-H "Content-type: application/json" \
4cache-control: no-cache
5accept: */*
6host: api-m.sandbox.paypal.com
7cookie: X-PP-SILOVER=name%3DSANDBOX3.API.1%26silo_version%3D1880%26app%3Dapiplatformproxyserv%26TIME%3D178943835%26HTTP_X_PP_AZ_LOCATOR%3Dsandbox.slc
8accept-encoding: gzip, deflate

Sample response

1HTTP/1.1 200
2status: 200
3date: Sat, 18 Aug 2018 05:09:36 GMT
4server: Apache
5paypal-debug-id: f3ed8e503c904,f3ed8e503c904
6http_x_pp_az_locator: sandbox.slc
7set-cookie: X-PP-SILOVER=name%3DSANDBOX3.API.1%26silo_version%3D1880%26app%3Dapiplatformproxyserv%26TIME%3D279607131%26HTTP_X_PP_AZ_LOCATOR%3Dsandbox.slc; Expires=Sat, 18 Aug 2018 05:39:36 GMT; domain=.paypal.com; path=/; Secure; HttpOnly,X-PP-SILOVER=; Expires=Thu, 01 Jan 1970 00:00:01 GMT
8vary: Authorization
9content-length: 252
10connection: close
11content-type: application/json;charset=UTF-8 {"user_id":"https://www.paypal.com/webapps/auth/identity/user/BMqJCufhBNpaMUN7cxRNSWT24TWDwEG6Wn35oGBVSZU","email":"LinkingTestAccount04@paypal.com","verified":"true","payer_id":"2MZ7GTCJCNLKW","verified_account":"false","email_verified":"true"}

Errors

Typically, errors returned by this API are due to invalid access tokens.

Additional information

• Consumer Referrals API reference
• Payments API reference