Downloadable Shopping Cart Onboarding

If you create downloadable ecommerce software packages for online sellers, you can set up your software package to include onboarding sellers with PayPal. To do this, your software package must retrieve the REST API credentials of the seller who downloaded the package. This page explains how to retrieve the seller's REST API credentials.

Know before you code

• You must be an approved partner to use this integration.
• You must have an access token.
• The payment features available to your sellers vary by the type of onboarding you choose. See onboarding options for more information.
• This integration uses the Partner Referrals API.

How it works

Your seller clicks on a sign-up link embedded in your software package which redirects them to PayPal for sign up. After completing sign up, PayPal shares the seller's REST API credentials with the software package.

Step 1: Generate a PayPal sign-up link

Call the Partner Referrals API to generate a sign-up link that redirects your sellers to sign up with PayPal. Passing your seller's information during the API call will pre-fill the PayPal sign-up flow with your seller's information.

Request sample

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/customer/partner-referrals
2-H "Content-Type: application/json"
3-H "Authorization: Bearer <Access-Token>"
4-d '{
5  "operations": [
6    {
7      "operation": "API_INTEGRATION",
8      "api_integration_preference": {
9        "rest_api_integration": {
10          "integration_method": "PAYPAL",
11          "integration_type": "FIRST_PARTY",
12          "first_party_details": {
13            "features": [
14              "PAYMENT",
15              "REFUND"
16            ],
17            "seller_nonce": "<Seller-Nonce>"
18          }
19        }
20      }
21    }
22  ],
23  "products": [
24    "EXPRESS_CHECKOUT"
25  ],
26  "legal_consents": [
27    {
28      "type": "SHARE_DATA_CONSENT",
29      "granted": true
30    }
31  ]
32}'

Step result

A successful request results in the following:

• A return status code of HTTP 201 Created.
• A HATEOAS self link. You can make a GET request to this link to retrieve the referral data and to reinitialize the action_url.
• A HATEOAS action_url link. You can place this link in a button or link tag to redirect your sellers to sign up with PayPal. The action_url expires after its first use. You can reinitialize it by making a GET request to the self link or by making another Partner Referrals API call.

Note: If you call GET /v2/customer/partner-referrals/{partner_referral_id}, the response returns only user data you have passed in about the seller and not any data the seller might have provided on paypal.com.

Sample response

1{
2  "links": [
3    {
4      "href": "https://api-m.sandbox.paypal.com/v2/customer/partner-referrals/NDZlMjQ1YTItMGQwNi00ZjlkLWJjNmYtYjcwODNiMWEzOTk0c203SWFJeU9NQ3gvcDEvbUVaS21rWFAvSWdlV1JKWktGRGxPUFA1MEZtUT12Mg==",
5      "rel": "self",
6      "method": "GET",
7      "description": "Read Referral Data shared by the Caller."
8    },
9    {
10      "href": "https://www.sandbox.paypal.com/us/merchantsignup/partner/onboardingentry?token=NDZlMjQ1YTItMGQwNi00ZjlkLWJjNmYtYjcwODNiMWEzOTk0c203SWFJeU9NQ3gvcDEvbUVaS21rWFAvSWdlV1JKWktGRGxPUFA1MEZtUT12Mg==",
11      "rel": "action_url",
12      "method": "GET",
13      "description": "Target WEB REDIRECT URL for the next action. Customer should be redirected to this URL in the browser."
14    }
15  ]
16}

Step 2: Embed the PayPal sign-up link

Use the following code and the action_url to redirect your seller to PayPal for sign up:

1<script>
2  function onboardedCallback(authCode, sharedId) {
3    fetch('/seller-server/login-seller', {
4      method: 'POST',
5      headers: {
6        'content-type': 'application/json'
7      },
8      body: JSON.stringify({
9        authCode: authCode,
10        sharedId: sharedId
11      })
12    }).then(function(res) {
13      if (!response.ok) {
14        alert("Something went wrong!");
15      }
16    });
17  }
18</script>
19<a target="_blank" data-paypal-onboard-complete="onboardedCallback" href="<Action-URL>&displayMode=minibrowser" data-paypal-button="true">Sign up for PayPal</a>
20<script id="paypal-js" src="https://www.sandbox.paypal.com/webapps/merchantboarding/js/lib/lightbox/partner.js"></script>

After the seller completes onboarding, PayPal returns an authCode and sharedId to the seller's browser. The authCode and sharedId are required to complete step 4. For PayPal to return the authCode and sharedId, you must pass a callback in the data-paypal-onboard-complete attribute. In this example, the onboardedCallback function passed to the data-paypal-onboard-complete attribute sends the authCode and sharedId to the seller's server.

Note: This code sample renders the PayPal sign up flow in a minibrowser by setting the displayMode query parameter to minibrowser. In addition, minibrowsers must conform to postMessage requirements.

Step 3: Redirect the seller back to their site

When your seller completes the sign-up flow, they are presented with a button that redirects them to the return URL you specified in the partner_config_override/return_url field of the Partner Referrals API. If you did not specify a return URL in your API call, then the button redirects the seller to the return URL set on your account. You can work with your account manager to set a return URL. If no return URL is set on your account, then the button sends the seller to the PayPal dashboard for their account.

During the redirect, PayPal loads the return URL in your seller's browser and attaches the following query parameters:

Sample request

https://<Return-URL>?merchantIdInPayPal=<Merchant-ID-In-PayPal>&permissionsGranted=false&accountStatus=BUSINESS_ACCOUNT&consentStatus=false&productIntentID=addipmt&isEmailConfirmed=true&returnMessage=To%20start%20accepting%20payments,%20please%20log%20in%20to%20PayPal%20and%20finish%20signing%20up.

Step 4: Get seller access token

When your seller completes the sign-up flow, PayPal returns an authCode and sharedId to your seller's browser. You use the authCode and sharedId to get the seller's access token. Then, you use this access token to get the seller's REST API credentials.

Sample request

In this step, use the following code to get the seller's access token:

1curl -X POST https://api-m.sandbox.paypal.com/v1/oauth2/token
2-u <Shared-ID>:
3-d 'grant_type=authorization_code&code=<Auth-Code>&code_verifier=<Seller-Nonce>'

Sample response

1{
2  "scope": "https://uri.paypal.com/services/payments/realtimepayment https://uri.paypal.com/services/payments/payment/authcapture openid https://uri.paypal.com/services/payments/refund https://uri.paypal.com/services/applications/webhooks",
3  "access_token": "A23AAHclqoiifoeiP9H4jLNZ7OJjcPlvdANa3UoJ2Zq5qn_kg-Mf9eaV_gW8X2H4a3cXYc4jwnwcLukxiST4SkPesqAw-rn5Q",
4  "token_type": "Bearer",
5  "expires_in": 28799,
6  "refresh_token": "R23AAG9SXLtr70FIgRGYWzFeon5pA8lwC6cX7F9pvK4db83uxptI5AuTw8jao55NowN5M37_1SBjvZ5kKAhoxZ4GtT1GacZEN5zdZP0AFjKU4N0-KYY6RYEk0rU4XW7D0878W54SYfbmE5pNHPnrA",
7  "nonce": "2020-02-05T15:43:54ZiBnhkZ7DMRJpzXd_AhUCfHgT2fPBWicqo1r7A2zbAj8"
8}

Note: Only use the seller's access token returned by grant_type=authorization_code in Step 5. For all other REST API calls that require an access token, use your access token.

Step 5: Get seller REST API credentials

Use the seller's access token to get your seller's REST API credentials:

Request sample

1curl -X GET https://api-m.sandbox.paypal.com/v1/customer/partners/{partner_merchant_id}/merchant-integrations/credentials/
2  -H 'Authorization: Bearer <Seller-Access-Token>'
3  -H 'Content-Type: application/json'

partner_merchant_id is the merchant ID of your PayPal account. To find the merchant ID of your PayPal account, log in to your PayPal account at paypal.com, click on the Settings icon, click on Business information, and look for PayPal Merchant ID. To find the merchant ID of your sandbox account, follow the same instructions on sandbox.paypal.com.

Sample response

1{
2  "client_id": "Ab27r3fkrQezHdcPrn2b2SYzPEldXx2dWgv76btVfI-eYF8KRAd2WxXAZyb0ETygSNeHBthzlxjlQ_qw",
3  "client_secret": "EAcTvpnDHZf4icl_2MPnt2gRpOxHVtaQJChWU3PrRbYR4uyvUXV6h4DWQjm7XOfdnk_OrEEWdxY2eUG3",
4  "payer_id": "CG5RZJV4NR5P4"
5}

You use your seller's REST API credentials for processing payments and handling refunds.

Next steps

Accept payments