Platform-level onboarding

DOCSCURRENT

Last updated: Feb 27th, 8:07am

Platform-level vaulting supports a payer using a saved payment method with many merchants. For example, a payer saves their payment method on a marketplace's website, and can then use their saved payment method with any merchant on the marketplace.

Take the following steps to onboard merchants for platform-level vaulting.

You can pre-fill the PayPal sign up flow with a merchant's information using the Partner Referrals API.

To generate a signup link that redirects merchants to sign up with PayPal, copy the following code and modify it.

Sample request

API used: Partner Referrals API

Express Checkout
PPCP
Save payment methods
Alternative payment methods

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 -H "PayPal-Auth-Assertion: PAYPAL-AUTH-ASSERTION" \
5 -H "PayPal-Partner-Attribution-Id: BN-CODE" \
6 -d '{
7    "operations": [
8      {
9        "operation": "API_INTEGRATION",
10        "api_integration_preference": {
11          "rest_api_integration": {
12            "integration_method": "PAYPAL",
13            "integration_type": "THIRD_PARTY",
14            "third_party_details": {
15              "features": [
16                "PAYMENT",
17                "REFUND"
18             ]
19            }
20          }
21        }
22      }
23    ],
24    "products": [
25      "EXPRESS_CHECKOUT"
26    ],
27    "legal_consents": [
28      {
29        "type": "SHARE_DATA_CONSENT",
30        "granted": true
31      }
32    ]
33}'

Modify the code

Modify the code in the sample request as follows:

Change ACCESS_TOKEN to your access token.
Change PAYPAL-AUTH-ASSERTION to your PayPal-Auth-Assertion token.
Change BN-CODE to your PayPal Attribution ID to receive revenue attribution. To find your BN code, see Code and Credential Reference.
Change products to the value you want for your merchants. The products array value determines which type of payment your merchant can accept. EXPRESS_CHECKOUT includes debit and credit cards, the PayPal button, and PayPal Credit. PPCP includes the PayPal button and advanced credit and debit cards.
Optional: Pass a tracking_id. You can use this ID to track the status of your merchant as they complete onboarding.

Step result

A successful request results in the following:

Return status code of HTTP 201 Created.
HATEOAS self link. You can make a GET request to this link to retrieve the referral data and refresh the action_url.
HATEOAS action_url link. You can place this link in a button or link tag to redirect your merchants to sign up with PayPal. The action_url expires after its first use. You can refresh 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 user data about the merchant you've passed in. The response doesn't include any data the merchant 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  }

To redirect the merchant to PayPal to sign up, place the action_url in a button or link. You can also render the PayPal sign-up flow in a mini-browser by using the following code:

1<script>
2      (function(d, s, id) {
3        var js, ref = d.getElementsByTagName(s)[0];
4        if (!d.getElementById(id)) {
5          js = d.createElement(s);
6          js.id = id;
7          js.async = true;
8          js.src = "https://www.paypal.com/webapps/merchantboarding/js/lib/lightbox/partner.js";
9          ref.parentNode.insertBefore(js, ref);
10        }
11      }(document, "script", "paypal-js"));
12    </script>
13    <a data-paypal-button="true" href="<Action-URL>&displayMode=minibrowser" target="PPFrame">Sign up for PayPal</a>
14  </div>

3. Redirect merchants

After your merchant completes the signup flow, they are redirected to the return URL specified in the partner_config_override/return_url field of the Partner Referrals API. If no return URL is set, the merchant is redirected to the PayPal dashboard for their account.

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

Parameter	Description
`merchantId`	The unique ID of the merchant in your system that you specified in the Partner Referrals API call in the `tracking_id` field.
`merchantIdInPayPal`	The merchant ID of your merchant's PayPal account.
`permissionsGranted`	A Boolean indicating whether the merchant granted you the permissions you specified in the Partner Referrals API call.
`accountStatus`	`BUSINESS_ACCOUNT` is sent if a business account was created. If a business account was not created, nothing is sent.
`consentStatus`	A Boolean indicating whether the merchant consented to share their credentials with you.
`productIntentId`	This value is set to `addipmt`.
`isEmailConfirmed`	A Boolean indicating whether the merchant has confirmed their email address with PayPal.
`returnMessage`	A message containing next steps for the merchant to take with PayPal. PayPal only sends this message for business accounts that do not have a confirmed email address. PayPal does not send this message for any account where product name is `PPCP`.
`riskStatus`	The product provisioning status. PayPal only sends this for accounts where product name is `PPCP`. Possible values are `SUBSCRIBED`, `SUBSCRIBED_WITH_LIMIT`, `DECLINED`, `MANUAL_REVIEW`, and `NEED_MORE_DATA.`

Sample request

Copy the following code and use it to redirect the merchant back to your site.

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

4. Track merchant onboarding status

Merchant onboarding is complete when the merchant has:

Created a PayPal account.
Granted you permission for the features you set.
Confirms the email address of the account.

To track your merchant's status in meeting these requirements, make a show merchant status call.

Sample request

1curl -v -X GET https://api-m.sandbox.paypal.com/v1/customer/partners/{partner_merchant_id}/merchant-integrations/{seller_merchant_id} \
2  -H "Content-Type: application/json" \
3  -H "Authorization: Bearer <Access-Token>" \
4  -H "PayPal-Auth-Assertion: PAYPAL-AUTH-ASSERTION" \
5  -H "PayPal-Partner-Attribution-Id: BN-CODE"

Modify the code

After you copy the code in the sample request, change Access-Token to your access token and modify the partner_merchant_id and the seller_merchant_id as follows:

The 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. Hover over your name or profile icon on the top right, select Account Settings> 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.

The seller_merchant_id is the merchant ID of the seller's PayPal account. To get your seller's merchant ID, look at the merchantIdInPayPal query parameter attached to the return URL when the seller is redirected back to your site. You can also query it directly by the tracking ID you specified in the Partner Referrals call by calling GET /v1/customer/partners/partner_id/merchant-integrations?tracking_id={tracking_id}.

Change the PAYPAL-AUTH-ASSERTION to your PayPal-Auth-Assertion token.

Change the BN-CODE to your PayPal Attribution ID to receive revenue attribution. To find your BN code, see Code and Credential Reference.

Step result

A successful request results in the following:

A return status code of HTTP 200 OK.
A JSON response body that shows referral data. This response body does not return user data but returns information on whether the merchant is onboarded and is eligible to process transactions.
The payments_receivable is true.
The primary_email_confirmed is true.
The oauth_third_party contains permissions granted.

Sample response with products set to PPCP

1{
2  "merchant_id": "CG5RZJV4NR5P4",
3  "tracking_id": "1537989077589",
4  "products": [
5    {
6      "name": "PPCP_CUSTOM"
7    }
8  ],
9  "payments_receivable": true,
10  "primary_email_confirmed": true,
11  "products.vetting status": "SUBSCRIBED",
12  "capabilities[name==CUSTOM_CARD_PROCESSING].status": "ACTIVE",
13  "capabilities[name==CUSTOM_CARD_PROCESSING].limits": "undefined",
14  "oauth_integrations": [{
15    "integration_type": "OAUTH_THIRD_PARTY",
16    "integration_method": "PAYPAL",
17    "oauth_third_party": [
18      {
19        "partner_client_id": "Af1bGDNgFBtbJvzEkG25zt4SoNQQ3ustiLm84GWXxe8nq_HE_0wCQ9SH8M1ScmSBURBIzPiCjr5gu-Dq",
20        "merchant_client_id": "AQ7u3fJkUH4cdCEBidsh5U_F1RQCGjglJQdNEEsXCzvQsGsS5MmC8Dk7_ug_IlkUASJezaGqQxQQfVhQ",
21        "scopes": ["https://uri.paypal.com/services/payments/realtimepayment", "https://uri.paypal.com/services/payments/refund", "https://uri.paypal.com/services/payments/payment/authcapture"]
22      }
23    ]
24  }]
25}

Sample response with products set to EXPRESS_CHECKOUT

1{
2  "merchant_id": "CG5RZJV4NR5P4",
3  "tracking_id": "1537989077589",
4  "products": [
5    {
6      "name": "EXPRESS_CHECKOUT"
7    }
8  ],
9  "payments_receivable": false,
10  "primary_email_confirmed": false,
11  "oauth_integrations": [{
12    "integration_type": "OAUTH_THIRD_PARTY",
13    "integration_method": "PAYPAL",
14    "oauth_third_party": [
15      {
16        "partner_client_id": "Af1bGDNgFBtbJvzEkG25zt4SoNQQ3ustiLm84GWXxe8nq_HE_0wCQ9SH8M1ScmSBURBIzPiCjr5gu-Dq",
17        "merchant_client_id": "AQ7u3fJkUH4cdCEBidsh5U_F1RQCGjglJQdNEEsXCzvQsGsS5MmC8Dk7_ug_IlkUASJezaGqQxQQfVhQ",
18        "scopes": ["https://uri.paypal.com/services/payments/realtimepayment", "https://uri.paypal.com/services/payments/refund", "https://uri.paypal.com/services/payments/payment/authcapture"]
19      }
20    ]
21  }]
22}

Next steps

After you've onboarded your merchants, choose the integration method that best suits your needs:

Feature	JavaScript SDK	Orders API	Payment Method Tokens API
Credit and debit cards	Supported	Supported	Supported
PayPal	Supported	Supported	Supported
Venmo	Supported	Not supported	Not supported
Save during purchase	Supported	Supported	Not supported
Save for purchase later	Supported	Not supported	Supported

Platform-level onboarding

1. Generate signup link

Sample request

Modify the code

Step result

Sample response

2. Add signup link to your site

3. Redirect merchants

Sample request

4. Track merchant onboarding status

Sample request

Modify the code

Step result

Sample response with products set to PPCP

Sample response with products set to EXPRESS_CHECKOUT

Next steps

We currently use cookies to improve and customize your experience on our site. If you accept, we’ll also use marketing cookies to show you personalized ads. Manage your cookies and learn more.