User Starts from Partner Website Integration

DOCS

Last updated: Feb 7th, 4:36pm

Important: PayPal Provisioning Platform is a limited-release solution available only to select partners at this time. For more information, reach out to your PayPal Account Manager.

When you want to start the user at your Partner website, you can choose different ways to complete the integration. You can either send two separate API calls to first onboard the account information then to add card data, or you can include the account information and card data in a single API call.

Both of these techniques require you to first onboard the user and link their data.

For details on how to add more cards outside the initial integration flow, see Add more cards.

For details on how to add card art in a separate API call, see Add card art.

Select how to send the data

To integrate P3 from the partner site, create a consumer referral resource and send the user's card information.

Select one of these two ways to send card information, depending on whether you want customers to be able to start P3 from PayPal:

Integration Technique	Advantage
Use two API calls	PayPal recommends this technique. The integration uses a call to the Consumer Referrals API to send user account data and uses a separate call to the Linked Instruments (Payment Network Transactions API) to send card data. This technique provides more flexibility when integrating the PayPal-initiated P3 flow. This technique can be used when the user originates from either the partner or PayPal site.
Use one API call	The integration sends a single call to the Consumer Referrals API to provide both user and card data. Choose this technique when the partner doesn't want customers to start P3 from PayPal.

Integration Technique

Advantage

Use two API calls

PayPal recommends this technique. The integration uses a call to the Consumer Referrals API to send user account data and uses a separate call to the Linked Instruments (Payment Network Transactions API) to send card data. This technique provides more flexibility when integrating the PayPal-initiated P3 flow. This technique can be used when the user originates from either the partner or PayPal site.

Use one API call

The integration sends a single call to the Consumer Referrals API to provide both user and card data. Choose this technique when the partner doesn't want customers to start P3 from PayPal.

Both techniques share the same steps to onboard a user, redirect a user to PayPal, and redirect a user to the partner site. The following sections include flow diagrams and code samples for each integration approach.

Integrate using two API calls

This approach makes a call to the Consumer Referrals API and a separate call to the Linked Instruments (Payment Network Transactions API).

Partner-initiated flow sequence diagram using two API calls

The following diagram illustrates the end-to-end partner-initiated flow using two API calls. The steps listed in the following sections refer to steps in the sequence diagram.

Partner-Initiated,Push,with,Consumer,Referrals,and,Linked,Instruments

Follow these steps to integrate a partner-initiated flow using two separate API calls.

Endpoints

Live: https://api-m.paypal.com/v1/customer/consumer-referrals

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

Select card to link and obtain authorization

Steps 1-2a: Enable user to select a card to link and make a first-party oAuth v2 call to return the access token needed. In this step, QWF0bmFXZ3d5d0p0 ... TVERuYWEzTGx6dnJJR3d2Yi0= is the Base64-encoded client id:secret value.

1POST /v1/oauth2/token HTTP/1.1
2Host: api-m.sandbox.paypal.com
3Accept: application/json
4Content-Type: application/x-www-form-urlencoded
5Authorization: Basic  
6QWF0bmFXZ3d5d0p0VkdManlQdU1yLUpiOUxvdWIxbUJEaV9nUDBSRlR5eUN2MFVva3dxZllYWmp5YjRrNUpZTDJxbVg2emYxRkxiUFZMYmU6RUtoUHI1YlozbnJJVU1sU2lFN1dteHV1am9FS1g4RlcyaHBJS3NJak1HSkhoM3YtcVZESXY2ay14ZzFLMmxTVERuYWEzTGx6dnJJR3d2Yi0=

Request

1grant_type=client_credentials&response_type=token

Response

In the response "A21AAHCQhC6ue2JTf6DN...wGVUTE8B8gx1lTpdwbKHJg"," is the access token.

1{"scope":"https://uri.paypal.com/services/wallet/card-accounts/update https://uri.paypal.com/services/wallet/card-accounts/external-update https://uri.paypal.com/services/applications/webhooks openid https://uri.paypal.com/services/customer/consumer-referrals/create","nonce":"2017-03-29T01:56:06ZhE-XlvFxz5ns7ceDQrw9405NpDZB_bbinI26J65ItiA","access_token":"A21AAHCQhC6ue2JTf6DNPSEXbDfhTTblcjdFUn3oNfHkYfabdv7Tw8D5bbPANpEf5fUzd4xFFB_wGVUTE8B8gx1lTpdwbKHJg","token_type":"Bearer","app_id":"APP-80W284485P519543T","expires_in":32399}

Create a consumer referral resource with user data

Steps 3-3a: Create a consumer referral resource for a customer with a credit card. This sample doesn't send card art or linked instruments. In this step, A21AAH...bKHJg is the access token from Step 2a response.

Note: PayPal only accepts five-digit zip codes. Nine-digit zip codes are interpreted as a new address.

1curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer/consumer-referrals \
2  -H "PayPal-Request-Id: 12345" \
3  -H "Content-Type: application/json" \
4  -H "Authorization: Bearer
5      A21AAHCQhC6ue2JTf6DNPSEXbDfhTTblcjdFUn3oNfHkYfabdv7Tw8D5bbPANpEf5fUzd4xFFB_wGVUTE8B8gx1lTpdwbKHJg" \
6  -d '{
7      "person_details":{
8          "names":[
9              {
10                  "given_name":"Mike",
11                  "surname":"Sanders"
12              }
13          ],
14          "phone_contacts":[
15              {
16                  "phone":{
17                      "country_code":"1",
18                      "national_number":"4083131000"
19                  },
20                  "phone_type":"HOME"
21              }
22          ],
23          "addresses":[
24              {
25                  "address":{
26                      "line1":"2141 N 1st Street",
27                      "line2":"",
28                      "city":"San Jose",
29                      "state":"California",
30                      "country_code":"US",
31                      "postal_code":"95131"
32                  },
33                  "address_type":"HOME"
34              }
35          ],
36          "email_addresses":[
37              {
38                  "email_address":"rmenon-032602@gmail.com",
39                  "primary":true,
40                  "confirmed":true
41              }
42          ],
43          "locale":"en_US"
44      },
45      "paypal_account_properties":{
46          "account_country_code":"US"
47      }
48  }

Response

In the response QUFHSlBO...qcmFYWQ is the PayPal login redirect url with multiple query parameters.

1{"referral_id":"QUFHSlBOcmZuLzE4OE10ZXI0alFDTFo1MVFzUGx6WUY3Mk9ZYTRudVJuZGxDTUhHZEMyUkNkaFg3UktqcmFYWQ","person_details":{"names":[{"given_name":"Super","surname":"Mario"}],"phone_contacts":[{"phone":{"country_code":"1","national_number":"4083131000"},"phone_type":"MOBILE"}],"addresses":[{"address":{"line1":"2141 N 1st Street","line2":"","city":"San Jose","state":"California","country_code":"US","postal_code":"95131"},"address_type":"HOME"}],"email_addresses":[{"email_address":"supermario100611@gmail.com","confirmed":false,"primary":true}],"identity_documents":[],"locale":"en_US"},"links":[{"rel":"action_url","href":"https://www.sandbox.paypal.com/consumeronboarding/entry?referralid=QUFHSlBOcmZuLzE4OE10ZXI0alFDTFo1MVFzUGx6WUY3Mk9ZYTRudVJuZGxDTUhHZEMyUkNkaFg3UktqcmFYWQ","method":"GET"}]}

Linked Instruments call with card data and reference_instrument_id

Steps 4-4b: Pass the referral_id from the Consumer Referral API request into the Linked Instruments (Payment Network Transactions API) method. In this step, 1234 is the unique id for idempotency.

1POST /v1/payment-networks/linked-instruments HTTP/1.1
2Host: api-m.sandbox.paypal.com
3Content-Type: application/json
4Authorization: Bearer A21AAEPYT7ek70fthWyH8rd6LAxcoIKuTlYiou_imD9inhkB6GAg7tcxXW5yeZTOHf2oAqSbZ43HouRHELrUzlRUROLOSKimA
5PayPal-Request-Id: 12345
6Accept: application/json
7Accept-Language: en_US
8Content-Type: application/x-www-form-urlencoded

Request

In the request:

QUFHSlBOcmZuLz...FYWQ is the referral ID.

GPPSTXo6oYXfH1OxQSTVKw is the JWE encrypted PAN number. See Encryption for more information.

B2121XYZ is the partner-provided reference_financial_instrument_id to be echoed back in webhook payload.

1{
2    "partner_data":{
3        "consumer":{
4            "authentication_factors":{
5                "cvv":false,
6                "challenge_questions":true,
7                "logged_in":true,
8                "otp_methods":[
9                    "SMS",
10                    "EMAIL"
11                ],
12                "biometric_methods":[
13                    "FACE_RECOGNITION"
14                ],
15                "trusted_device_factors":[
16                    "TRUSTED_DEVICE_FINGERPRINT_MATCH"
17                ]
18            }
19        }
20    },
21    "referral_id":" QUFHSlBOcmZuLzE4OE10ZXI0alFDTFo1MVFzUGx6WUY3Mk9ZYTRudVJuZGxDTUhHZEMyUkNkaFg3UktqcmFYWQ",
22    "card_accounts":[
23        {
24            "identifier":"eyJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiUlNBLU9BRVAifQ.FNGgAyitajvujmUMOnXQsSrsEv8jUaBTx3gmaCbspSxqKtiu_8NPLIRoEp3sUhM_SoYfmK4GP--iOST215W7XopN_awjnjDYGuMYd31lT1o02xg1wJjibdHtQpcW3RrBFoEyvmrfN44ZSaXhgkhwaZ1cGR_KgbdvtWm2xEaCV_W6HC78gs5A_4REftp40CT9hC-9lq1TQZh5pQxSRnmPihDfBbkXIm5Arciiyu5f7c6GP_TwRFJmA3gsBFVugUvonT_2QCLAgIASFsFUjvfuxGWgI03diGsKAWxvTniwAW05PnSG5ApK0mykuV50GyJBm9GIcWj1kgZuZcLO3FknWQ.maRfYRn9ObALsUzMLC2spQ.k0BiPAMLNwRIPYRsDnhs7ZBKYWDZghKrqPsD5Ukdefg.GPPSTXo6oYXfH1OxQSTVKw",
25            "reference_financial_instrument_id":"B2121XYZ",
26            "expiry_date":"2020-12",
27            "billing_address":{
28                "address_line_1":"2211 N 1st Street",
29                "admin_area_1":"CA",
30                "admin_area_2":"San Jose",
31                "country_code":"US",
32                "postal_code":"95035"
33            },
34            "account_holder_name":{
35                "given_name":"John",
36                "surname":"Smith"
37            }
38        }
39    ]
40}

Response

In the response 30ffdc0d4e3ce is used to log all debug IDs for PayPal support.

1HTTP/1.1 202 Accepted
2Date: Thu, 05 Mar 2020 21:01:41 GMT
3Server: Apache
4paypal-debug-id: 30ffdc0d4e3ce
5PayPal-Request-Id: 12345
6
7{"links":[{"href":"https://www.sandbox.paypal.com/myaccount/money/cards/pull/p3","rel":"redirect","method":"GET","encType":"application/json"}]}

Redirect user to PayPal

Steps 5-8: After you pass in the referral_id, if Step 4a response returns a 202 success, redirect the user to PayPal for login and consent. Otherwise see API Error codes for a list of the error codes that can be returned here. QUFHSlBOcm...scope_group_provisioning_platform shows how to construct redirect url with referral id, partner return url, state, and scope parameters.

1https://www.sandbox.paypal.com/consumeronboarding/entry?referralid= QUFHSlBOcmZuLzE4OE10ZXI0alFDTFo1MVFzUGx6WUY3Mk9ZYTRudVJuZGxDTUhHZEMyUkNkaFg3UktqcmFYWQ &redirect_uri=https://partner-return-url &state=channel=Mobile&Linkid=test&scope=scope_group_provisioning_platform

Listen to Webhook payload sent to partner

Step 9: Receive webhook payload. In this step,:

B2121XYZ = Echo back the reference_financial_instrument_id sent by partner in Linked Instrument call. The partner_financial_instrument_id = reference_financial_instrument_id.

CC-HFPEET8KTJF9L is the PayPal card identifier needed to make Lifecycle API calls.

"paypal_customer_id": "6PN79VDMX6566" is the PayPal encrypted account number needed for PayPal support.

1{
2    "id": "WH-9LG8099179700735B-801161897N370874M",
3    "event_version": "1.0",
4    "create_time": "2020-02-05T22:29:38.000Z",
5    "resource_type": "INSTRUMENT",
6    "event_type": "PAYMENT_NETWORKS.INSTRUMENT.LINKED-ACCOUNT-UPDATED",
7    "summary": "An instrument was successfully added.",
8    "resource": {
9        "partner_financial_instrument_id": "B2121XYZ",
10        "financial_instrument_id": "CC-HFPEET8KTJF9L",
11        "event": {
12            "event_type": "INSTRUMENT_ADDED",
13            "event_reason": "USER_INITIATED"
14        },
15        "customer": {
16            "paypal_customer_id": "6PN79VDMX6566"
17        }
18    },
19    "links": [
20        {
21            "href": "https:\/\/api-m.sandbox.paypal.com\/v1\/notifications\/webhooks-events\/WH-9LG8099179700735B-801161897N370874M",
22            "rel": "self",
23            "method": "GET"
24        },
25        {
26            "href": "https:\/\/api-m.sandbox.paypal.com\/v1\/notifications\/webhooks-events\/WH-9LG8099179700735B-801161897N370874M\/resend",
27            "rel": "resend",
28            "method": "POST"
29    ]
30}

Confirm card to use

Step 11: User opts to Set Preferred Card on PayPal Wallet.

Store user and card

Step 12: PayPal stores User and Card in permanent storage.

Return to partner with authorization code

Steps 13-14: Return to the partner using the return URL. In this step, QWF0bmFXZ3d5d0...JJR3d2Yi0= is the Base64-encoded client id : secret value.

1https://partner-return-url?code=C21AAFQ_fyBghy0cey3BBFE-NOpIWd50WPrCwdpWBx3hIajwIED-fBwo0Sa1o696SySy5uE5sPlpDoEhK_tBCFsb_NJpWs2sA&state=channel=Mobile&Linkid=test

Exchange refresh token with authorization code

Step 15: Exchange authorization code for a refresh token.

1POST /v1/oauth2/token HTTP/1.1
2Authorization: Basic QWF0bmFXZ3d5d0p0VkdManlQdU1yLUpiOUxvdWIxbUJEaV9nUDBSRlR5eUN2MFVva3dxZllYWmp5YjRrNUpZTDJxbVg2emYxRkxiUFZMYmU6RUtoUHI1YlozbnJJVU1sU2lFN1dteHV1am9FS1g4RlcyaHBJS3NJak1HSkhoM3YtcVZESXY2ay14ZzFLMmxTVERuYWEzTGx6dnJJR3d2Yi0=
3Host: api-m.sandbox.paypal.com
4Accept: application/json
5Accept-Language: en_US
6Content-Type: application/x-www-form-urlencoded

Request

In the request C21AAFQ_fy...NJpWs2sA is the authorization code from Step 13.

1grant_type=authorization_code&code=C21AAFQ_fyBghy0cey3BBFE-NOpIWd50WPrCwdpWBx3hIajwIED-fBwo0Sa1o696SySy5uE5sPlpDoEhK_tBCFsb_NJpWs2sA

Response

In the response:

R23AAG...0NqLNyg is the refresh token to be stored for future lifecycle calls to obtain access token.

A23AAH0nv7...7BNsg is the first-time access token. This token expires in 8 hours. It can be ignored if it is not initially needed.

1{"token_type":"Bearer","expires_in":"28799","refresh_token":"R23AAGPIvifgk-ZFFDfuv10JwJwVcQ3mab2NefbOPawZ2rfguplZw3FS9qpTUWmJe88Ty5DuO7zDUIdgpvBAO91VzWF-u9wez1P3TlbrE-5ddd71NXKwaqMgE3CGTN8CrllwcVAEwB7pXu0NqLNyg", "access_token":"A23AAH0nv75jRyVVGz8B3kVRI59GGnANLgeMnwDJB6qap8LOPkBfe_KpIqxMQPgCH_pryUTv33KhmwdmT4A3votjFOP07BNsg"}

Integrate using one API call

This approach sends the user and card data in a single call to the Consumer Referrals API call. This method can be used when the P3 flow initiates from the partner site only.

Partner-initiated flow using a single API call

The following diagram shows the flow in which the Consumer Referrals API combines both the user and card data into a single API call.

Partner-Initiated,single,call

oAuth v2 first party call

Steps 1-2a: Select card to link and obtain first-party authorization. In this step, QWF0bmFXZ3d5d0p0 ... TVERuYWEzTGx6dnJJR3d2Yi0= is the Base64-encoded client id:secret value.

1POST /v1/oauth2/token HTTP/1.1
2Host: api-m.sandbox.paypal.com
3Accept: application/json
4Content-Type: application/x-www-form-urlencoded
5Authorization: Basic  
6QWF0bmFXZ3d5d0p0VkdManlQdU1yLUpiOUxvdWIxbUJEaV9nUDBSRlR5eUN2MFVva3dxZllYWmp5YjRrNUpZTDJxbVg2emYxRkxiUFZMYmU6RUtoUHI1YlozbnJJVU1sU2lFN1dteHV1am9FS1g4RlcyaHBJS3NJak1HSkhoM3YtcVZESXY2ay14ZzFLMmxTVERuYWEzTGx6dnJJR3d2Yi0=

Request

1grant_type=client_credentials&response_type=token

Response

In the response A21AAHCQhC6ue2JTf6DN...wGVUTE8B8gx1lTpdwbKHJg"," is the access token.

1{"scope":"https://uri.paypal.com/services/wallet/card-accounts/update https://uri.paypal.com/services/wallet/card-accounts/external-update https://uri.paypal.com/services/applications/webhooks openid https://uri.paypal.com/services/customer/consumer-referrals/create","nonce":"2017-03-29T01:56:06ZhE-XlvFxz5ns7ceDQrw9405NpDZB_bbinI26J65ItiA","access_token":"A21AAHCQhC6ue2JTf6DNPSEXbDfhTTblcjdFUn3oNfHkYfabdv7Tw8D5bbPANpEf5fUzd4xFFB_wGVUTE8B8gx1lTpdwbKHJg","token_type":"Bearer","app_id":"APP-80W284485P519543T","expires_in":32399}

Consumer Referral call with user and card data

Steps 3-4: Note that when you use two api calls, the Consumer Referral API call in Step 3 includes just the user payload. When you combine the APIs into a single call, the Consumer Referral API call in Step 3 includes card payload as well as user payload. In this step, A21AAHCQhC6ue2JTf6... TE8B8gx1lTpdwbKHJg is the access token from the Step 2a response.

Note: PayPal only accepts five-digit zip codes. Nine-digit zip codes are interpreted as a new address.

1POST /v1/customer/consumer-referrals HTTP/1.1
2Host: api-m.sandbox.paypal.com
3Content-Type: application/json
4Authorization: Bearer A21AAHCQhC6ue2JTf6DNPSEXbDfhTTblcjdFUn3oNfHkYfabdv7Tw8D5bbPANpEf5fUzd4xFFB_wGVUTE8B8gx1lTpdwbKHJg
5Accept: application/json
6Accept-Language: en_US
7Content-Length: 1311

Request

1{
2  "person_details": {
3    "names": [
4      {
5        "given_name": "Mike",
6        "surname": "Sanders"
7      }
8    ],
9    "phone_contacts": [
10      {
11        "phone": {
12          "country_code": "1",
13          "national_number": "4083131000"
14        },
15        "phone_type": "HOME"
16      }
17    ],
18    "addresses": [
19      {
20        "address": {
21          "line1": "2141 N 1st Street",
22          "line2": "",
23          "city": "San Jose",
24          "state": "California",
25          "country_code": "US",
26          "postal_code": "95131"
27        },
28        "address_type": "HOME"
29      }
30    ],    
31    "email_addresses": [
32      {
33        "email_address": " p3_6100808@pp.com",
34        "primary": true,
35        "confirmed": true
36      }
37    ],
38    "locale": "en_US"
39  },
40  "paypal_account_properties": {
41    "account_country_code": "US"
42  },
43  "linked_instruments": {
44    "card_accounts": [
45      {
46        "identifier": "6011493404351851",
47                    "reference_financial_instrument_id": "ref1234",
48                    "expiry_date": "2020-12",
49                    "billing_address": {
50                        "address_line_1": "2211 N 1st Street",
51                        "admin_area_1": "CA",
52                        "admin_area_2": "San Jose",
53                        "country_code": "US",
54                        "postal_code": "95035"
55                    },
56                    "account_holder_name": {
57                        "given_name": "Mike",
58                        "surname": "Sanders"
59                    }
60
61      }
62    ]
63  }
64}

Response

In the response QUFIOUhDa...ZhUHJXaGNpSA is the PayPal login redirect url with multiple query parameters.

1{"referral_id":"QUFIOUhDaVl0SlNMVkRleTFBdS9XaERibG5WWHhid2hpVHg1RS8zOUE3Nld5d0EwUi93aldFVXZhUHJXaGNpSA","person_details":{"names":[{"given_name":"Mike","surname":"Sanders"}],"phone_contacts":[{"phone":{"country_code":"1","national_number":"4083131000"},"phone_type":"HOME"}],"addresses":[{"address":{"line1":"2141 N 1st Street","line2":"","city":"San Jose","state":"California","country_code":"US","postal_code":"95131"},"address_type":"HOME"}],"email_addresses":[{"email_address":"p3_6100808@pp.com","confirmed":true,"primary":true}],"identity_documents":[],"locale":"en_US"},"links":[{"rel":"action_url","href":"https://www.sandbox.paypal.com/consumeronboarding/entry?referralid=QUFIOUhDaVl0SlNMVkRleTFBdS9XaERibG5WWHhid2hpVHg1RS8zOUE3Nld5d0EwUi93aldFVXZhUHJXaGNpSA","method":"GET"}]

Steps 5-9: Construct redirect url with referral ID, partner return url, state, and scope parameters and confirm. In this step, QUFHSI...FYWQ shows how to construct the redirect URL with referral_id, partner return URL, state, and scope parameters.

1https://www.sandbox.paypal.com/consumeronboarding/entry?referralid= QUFHSlBOcmZuLzE4OE10ZXI0alFDTFo1MVFzUGx6WUY3Mk9ZYTRudVJuZGxDTUhHZEMyUkNkaFg3UktqcmFYWQ &redirect_uri=https://partner-return-url &state=channel=Mobile&Linkid=test&scope=scope_group_provisioning_platform

Webhook payload sent to partner

Step 10: In this step,:

"partner_financial_instrument_id": "B2121XYZ" echoes back reference_financial_instrument_id sent by partner in the Linked Instrument call. In this property partner_financial_instrument_id = reference_financial_instrument_id.

"financial_instrument_id": "CC-HFPEET8KTJF9L" is the PayPal card identifier needed to make lifecycle calls.

paypal_customer_id": "6PN79VDMX6566" is the PayPal-encrypted account number needed for PayPal support.

1{
2    "id": "WH-9LG8099179700735B-801161897N370874M",
3    "event_version": "1.0",
4    "create_time": "2020-02-05T22:29:38.000Z",
5    "resource_type": "INSTRUMENT",
6    "event_type": "PAYMENT_NETWORKS.INSTRUMENT.LINKED-ACCOUNT-UPDATED",
7    "summary": "An instrument was successfully added.",
8    "resource": {
9        "partner_financial_instrument_id": "B2121XYZ",
10        "financial_instrument_id": "CC-HFPEET8KTJF9L",
11        "event": {
12            "event_type": "INSTRUMENT_ADDED",
13            "event_reason": "USER_INITIATED"
14        },
15        "customer": {
16            "paypal_customer_id": "6PN79VDMX6566"
17        }
18    },
19    "links": [
20        {
21            "href": "https:\/\/api-m.sandbox.paypal.com\/v1\/notifications\/webhooks-events\/WH-9LG8099179700735B-801161897N370874M",
22            "rel": "self",
23            "method": "GET"
24        },
25        {
26            "href": "https:\/\/api-m.sandbox.paypal.com\/v1\/notifications\/webhooks-events\/WH-9LG8099179700735B-801161897N370874M\/resend",
27            "rel": "resend",
28            "method": "POST"
29
30    ]
31}

Return to partner with authorization code

Step 13: Use authorization code to return to the partner return URL. In this step, partner-return-url is the redirect url.

1https://partner-return-url?code=C21AAFQ_fyBghy0cey3BBFE-NOpIWd50WPrCwdpWBx3hIajwIED-fBwo0Sa1o696SySy5uE5sPlpDoEhK_tBCFsb_NJpWs2sA&state=channel=Mobile&Linkid=test

oAuth call to exchange refresh token with authorization code

Steps 15: Exchange refresh token. In this step, QWF0bmFXZ3d5d0p0VkdManl ... TGx6dnJJR3d2Yi0= is the Base64-encoded client id:secret value.

1POST /v1/oauth2/token HTTP/1.1
2Authorization: Basic QWF0bmFXZ3d5d0p0VkdManlQdU1yLUpiOUxvdWIxbUJEaV9nUDBSRlR5eUN2MFVva3dxZllYWmp5YjRrNUpZTDJxbVg2emYxRkxiUFZMYmU6RUtoUHI1YlozbnJJVU1sU2lFN1dteHV1am9FS1g4RlcyaHBJS3NJak1HSkhoM3YtcVZESXY2ay14ZzFLMmxTVERuYWEzTGx6dnJJR3d2Yi0=
3Host: api-m.sandbox.paypal.com
4Accept: application/json
5Accept-Language: en_US
6Content-Type: application/x-www-form-urlencoded

Request

In this request C21AAFQ_fyBghy0cey3BBFE ... tBCFsb_NJpWs2sA is the authorization code from Step 13.

1grant_type=authorization_code&code=C21AAFQ_fyBghy0cey3BBFE-NOpIWd50WPrCwdpWBx3hIajwIED-fBwo0Sa1o696SySy5uE5sPlpDoEhK_tBCFsb_NJpWs2sA

Response

In this response:

R23AAGPIvifgk- ... VAEwB7pXu0NqLNyg is the refresh token to be stored for future lifecycle calls to get access token.

A23AAH0nv75jRyVVGz8B3 ... A3votjFOP07BNsg is the first-time access token. It expires in 8 hours. It can be ignored if not needed initially.

1{"token_type":"Bearer","expires_in":"28799","refresh_token":"R23AAGPIvifgk-ZFFDfuv10JwJwVcQ3mab2NefbOPawZ2rfguplZw3FS9qpTUWmJe88Ty5DuO7zDUIdgpvBAO91VzWF-u9wez1P3TlbrE-5ddd71NXKwaqMgE3CGTN8CrllwcVAEwB7pXu0NqLNyg", "access_token":"A23AAH0nv75jRyVVGz8B3kVRI59GGnANLgeMnwDJB6qap8LOPkBfe_KpIqxMQPgCH_pryUTv33KhmwdmT4A3votjFOP07BNsg"}

Store user and card data

Step 15a: Response

1{{"token_type":"Bearer","expires_in":"28799","refresh_token":"R23AAGPIvifgk-ZFFDfuv10JwJwVcQ3mab2NefbOPawZ2rfguplZw3FS9qpTUWmJe88Ty5DuO7zDUIdgpvBAO91VzWF-u9wez1P3TlbrE-5ddd71NXKwaqMgE3CGTN8CrllwcVAEwB7pXu0NqLNyg", "access_token":"A23AAH0nv75jRyVVGz8B3kVRI59GGnANLgeMnwDJB6qap8LOPkBfe_KpIqxMQPgCH_pryUTv33KhmwdmT4A3votjFOP07BNsg"}

See User starts from PayPal if the partner wants users to be able to also start P3 from PayPal in addition to starting from the partner site. It's easier to make this addition if you have already implemented the integrate using two APIs approach.

See Integration Features for optional features you can add to your integrations to enhance the user experience.

User Starts from Partner Website Integration

Select how to send the data

Integrate using two API calls

Partner-initiated flow sequence diagram using two API calls

Endpoints

Select card to link and obtain authorization

Request

Response

Create a consumer referral resource with user data

Response

Linked Instruments call with card data and reference_instrument_id

Request

Response

Redirect user to PayPal

Listen to Webhook payload sent to partner

Confirm card to use

Store user and card

Return to partner with authorization code

Exchange refresh token with authorization code

Request

Response

Integrate using one API call

Partner-initiated flow using a single API call

oAuth v2 first party call

Request

Response

Consumer Referral call with user and card data

Request

Response

Redirect to PayPal for login and consent

Webhook payload sent to partner

Return to partner with authorization code

oAuth call to exchange refresh token with authorization code

Request

Response

Store user and card data

Next