Platform-level onboarding

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.

1. Generate signup link

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

curl -v -X POST https://api-m.sandbox.paypal.com/v2/customer/partner-referrals \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'PayPal-Partner-Attribution-Id: BN-CODE' \
  -H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
  -d '{
    "operations": [
      {
        "operation": "API_INTEGRATION",
        "api_integration_preference": {
          "rest_api_integration": {
            "integration_method": "PAYPAL",
            "integration_type": "THIRD_PARTY",
            "third_party_details": {
              "features": [
                "PAYMENT",
                "REFUND"
              ]
            }
          }
        }
      }
    ],
    "products": [
      "EXPRESS_CHECKOUT"
    ],
    "legal_consents": [
      {
        "type": "SHARE_DATA_CONSENT",
        "granted": true
      }
    ]
  }'

Modify the code

Modify the code in the sample request as follows:

Step result

A successful request results in the following:

Sample response

{
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v2/customer/partner-referrals/NDZlMjQ1YTItMGQwNi00ZjlkLWJjNmYtYjcwODNiMWEzOTk0c203SWFJeU9NQ3gvcDEvbUVaS21rWFAvSWdlV1JKWktGRGxPUFA1MEZtUT12Mg==",
      "rel": "self",
      "method": "GET",
      "description": "Read Referral Data shared by the Caller."
    },
    {
      "href": "https://www.sandbox.paypal.com/us/merchantsignup/partner/onboardingentry?token=NDZlMjQ1YTItMGQwNi00ZjlkLWJjNmYtYjcwODNiMWEzOTk0c203SWFJeU9NQ3gvcDEvbUVaS21rWFAvSWdlV1JKWktGRGxPUFA1MEZtUT12Mg==",
      "rel": "action_url",
      "method": "GET",
      "description": "Target WEB REDIRECT URL for the next action. Customer should be redirected to this URL in the browser."
    }
  ]
}

2. Add signup link to your site

To redirect the merchant to PayPal for 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:

<script>
  (function (d, s, id) {
    var js,
      ref = d.getElementsByTagName(s)[0];
    if (!d.getElementById(id)) {
      js = d.createElement(s);
      js.id = id;
      js.async = true;
      js.src =
        "https://www.paypal.com/webapps/merchantboarding/js/lib/lightbox/partner.js";
      ref.parentNode.insertBefore(js, ref);
    }
  }(document, "script", "paypal-js"));
</script>

<a data-paypal-button="true" href="<Action-URL>&displayMode=minibrowser" target="PPFrame"> Sign up for PayPal </a>

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:

Sample request

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

https://<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:

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

Sample request

curl -v -X GET https://api-m.sandbox.paypal.com/v1/customer/partners/{PARTNER-MERCHANT-ID}/merchant-integrations/{SELLER-MERCHANT-ID} \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'PayPal-Partner-Attribution-Id: BN-CODE' \
  -H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT'

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 BN-CODE to your PayPal Attribution ID to receive revenue attribution. To find your BN code, see Code and Credential Reference.

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

Step result

A successful request results in the following:

Sample response

Sample responses with the products parameter set to PPCP and EXPRESS_CHECKOUT are as follows.

{
  "merchant_id": "CG5RZJV4NR5P4",
  "tracking_id": "1537989077589",
  "products": [
    {
      "name": "PPCP_CUSTOM"
    }
  ],
  "payments_receivable": true,
  "primary_email_confirmed": true,
  "products.vetting status": "SUBSCRIBED",
  "capabilities[name==CUSTOM_CARD_PROCESSING].status": "ACTIVE",
  "capabilities[name==CUSTOM_CARD_PROCESSING].limits": "undefined",
  "oauth_integrations": [
    {
      "integration_type": "OAUTH_THIRD_PARTY",
      "integration_method": "PAYPAL",
      "oauth_third_party": [
        {
          "partner_client_id": "Af1bGDNgFBtbJvzEkG25zt4SoNQQ3ustiLm84GWXxe8nq_HE_0wCQ9SH8M1ScmSBURBIzPiCjr5gu-Dq",
          "merchant_client_id": "AQ7u3fJkUH4cdCEBidsh5U_F1RQCGjglJQdNEEsXCzvQsGsS5MmC8Dk7_ug_IlkUASJezaGqQxQQfVhQ",
          "scopes": [
            "https://uri.paypal.com/services/payments/realtimepayment",
            "https://uri.paypal.com/services/payments/refund",
            "https://uri.paypal.com/services/payments/payment/authcapture"
          ]
        }
      ]
    }
  ]
}

Next steps

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