Connected Onboarding Integration Guide

Important: PayPal for Marketplaces is available to select partners for approved use cases. For more information, reach out to your PayPal account manager or contact us:

Overview

This guide shows you how to use the Connected path integration method to onboard your merchants so they can accept PayPal payments.

New Progressive onboarding: Enables buyers to easily pay with PayPal for all merchants, even those merchants who do not yet have PayPal accounts. Merchants receive an email to complete PayPal signup after their first PayPal order. Learn more about Progressive onboarding.

Upfront onboarding

With Upfront onboarding, you post a PayPal signup link on your website for your merchants and PayPal handles the rest. This signup flow uses an in-context experience to keep your merchants on your website and minimizes the number of pages to navigate. This process is fast and intuitive so more users are likely to complete it.

Here is how it works:

  • If your merchants already have a PayPal Business account, the merchants must agree to grant permission to you, the partner, to facilitate payments on their behalf. After they agree, they can accept PayPal payments.

  • If your merchants do not have a PayPal Business account, they are prompted to create one, after which they can grant you consent.

To implement this setup experience for your merchants, you can integrate with our partner-referrals API, which enables you to pre-fill the PayPal signup form with information you already have. Your merchants have fewer form fields to fill out, which lets them set up more quickly. This approach requires calling the PayPal REST APIs.

Note: Although PayPal recommends the Upfront method, PayPal also provides a URL method for Connected onboarding. While the URL method requires less setup, it does require that your merchants complete all signup fields. You use a URL with static parameters to direct the merchant to PayPal. You do not have to call the REST API to pre-fill information but you might need to whitelist the return URL.

Prerequisites

Before you can use the Connected Onboarding API:

Integration steps

Tip: Try the Connected Onboarding API demo.
  • Click the Call Prefill API button to begin the demo.
  • At the end of the demo, view API history to see request and response information
1. Required Call the REST API.
2. Required Display the signup form in a mini-browser.
3. Required Your merchant confirms their email address.
4. Optional Show your merchant's account status.
5. Optional Connect with setup-complete webhook event to enable PayPal payments for your customers. Webhooks will only work once the partner has met all prerequisites above and the merchant has confirmed their email and granted permissions to their account.

Note: Merchants in all countries other than the US must grant permissions to the partner. Merchants can skip this step but the best practice is that the partner complete set up by either:

Call the REST API

Call this API endpoint and pass parameters in the request body:

POST /v1/customer/partner-referrals
  • customer_data. The merchant's personal and business data.

    For information about the category and sub_category values in customer data, see business categories and subcategories.

  • requested_capabilities. Indicates how the merchant integrates with you. To call PayPal APIs on the merchant's behalf, you must enable the API_INTEGRATION capability.

  • web_experience_preference. The customizations for the merchant's signup process.

  • collected_consents. The consents to collect from the merchant.

  • products. Set this to EXPRESS_CHECKOUT.

PayPal returns:

  • A HATEOAS link that shows the referral data. For example:

    GET "https://api.paypal.com/v1/customer/partner-referrals/ZDM4ZT...
    
  • An action_url that redirects the merchant to complete the signup process.

To help prevent data theft and potential misuse, the URL expires after the first use, even if the merchant has not completed the onboarding process. To enable merchants to return to the onboarding process, you can use the HATEOAS link or use the following call to reinitialize an expired URL:

GET /v1/customer/partner-referrals/partner-referral-id

For information and a sample request, see create partner referral in the Partner Referrals API reference.

Note: All parameters are optional. PayPal prompts the user for any data that you omit. Even if you send no data, PayPal creates the action URL.

The following topics present more detail about the partner-referrals parameters:

customer_data

Provides account information for the merchant:

  • customer_type. Set to MERCHANT.
  • partner_specific_identifiers. Set TRACKING_ID to the unique ID that you use for the seller in your system. When processing the account information, PayPal automatically selects a currency and language based on the country code specified in the merchant's business or personal data. You can omit parameters such as preferred_language_code and primary_currency_code. Use these parameters to override the default language or currency.

For an example that includes the customer_data parameter, see create partner referral in the Partner Referrals API reference.

requested_capabilities

Defines the capabilities, or types of integrations, you are implementing with a merchant. API_INTEGRATION enables you to call PayPal APIs on behalf of the merchant. The following code snippet specifies API_INTEGRATION with PayPal REST APIs, using third-party authorization.

"requested_capabilities": [{
  "capability": "API_INTEGRATION",
  "api_integration_preference": {
    "partner_id": "partner-payer-id",
    "rest_api_integration": {
      "integration_method": "PAYPAL",
      "integration_type": "THIRD_PARTY"
    },
    "rest_third_party_details": {
      "partner_client_id": partner_client_id,
      "feature_list": [
        "PAYMENT",
        "REFUND"
      ]
    }
  }
}]

Third-party authorization requires that you get REST API permission from the merchant. Based on the features that you specify, PayPal generates and assigns a set of API permissions to you. During the setup flow, the merchant must agree to these permissions.

See Connected account permissions for a list of supported features.

web_experience_preference

Personalizes the account setup process. For example, you can display your logo in the background to keep the merchant oriented to your site. If you show the signup pages in a mini-browser, you can omit this field. See Display the signup form in a mini-browser.

This code snippet sets the partner_logo_URL, return_URL, and action_renewal_URL values in the web_experience_preference object:

"web_experience_preference": {
  "partner_logo_url": "https://example.com/image.jpg",
  "return_url": "https://example.com/return-from-pre-fill-flow",
  "action_renewal_url": "https://example.com/renew-pre-fill-url"
}
collected_consents

Consents that you need for the merchant to leverage the pre-fill feature. To indicate that the merchant has granted permission to share data with PayPal, specify the collected consents:

"collected_consents": [{
  "type": "SHARE_DATA_CONSENT",
  "granted": true
}]
products

Passes the PayPal product that the merchant uses. Currently, Express Checkout is the only PayPal product for which you can onboard a merchant.

"products": [
  "EXPRESS_CHECKOUT"
]

Display the signup form in a mini-browser

The action URL links to the PayPal integrated signup flow. When merchants click the link, they go through the signup process with the merchant data that you passed pre-filled in the forms.

You can display the PayPal signup form in a mini-browser to streamline the experience for your merchants:

<div dir="ltr" style="text-align: left;" trbidi="on">
  <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="<partner_onboarding_url>&displayMode=minibrowser" target="PPFrame">Sign up for PayPal </a>
</div>

In this code, replace partner_onboarding_url with your action_url which you received as part of the referral API call. The merchant completes the signup and setup flows and returns to your site.

Your merchant confirms their email address

After the merchant's account is created, the merchant receives a welcome email. Your merchants must click a link in the email and follow the instructions to confirm the email address on file.

Show your merchant's account status

To show status information for merchants who were onboarded by a partner, include the ID of the partner and the ID of the merchant in the request:

curl -v -X GET https://api.sandbox.paypal.com/v1/customer/partners/U6E69K99P3G88/merchant-integrations/8LQLM2ML4ZTYU \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer Access-Token"

The response shows the account status:

{
    "merchant_id": "8LQLM2ML4ZTYU",
    "products": [
    {
        "name": "EXPRESS_CHECKOUT"
    }],
    "payments_receivable": true,
    "primary_email_confirmed": true,
    "oauth_integrations": [
    {
        "integration_type": "OAUTH_THIRD_PARTY",
        "integration_method": "BRAINTREE",
        "oauth_third_party": [
        {
            "partner_client_id": "AZqTbhAo7fUgX2BQW5l-yYEHYY_C8FDUkiPP_6Cw7P35cQID26rsWVWXzgRQ",
            "merchant_client_id": "ARj22pLzUWaTt_RFAlFvn_dC6OpETq1HK_n49nyuDf4i5dqPBZmDk6X1u9JytrtMGaDExCvKSGCOwRbO",
            "scopes": ["https://uri.paypal.com/services/payments/payment/authcapture", "https://uri.paypal.com/services/payments/realtimepayment"],
            "access_token": "access_token$sandbox$s4dw8tjsz88cg7mh$45bdde2cfa55c1b060a409824b48b8d3",
            "refresh_token": "refresh_token$sandbox$s4dw8tjsz88cg7mh$b1dfdbbdbaa7b9165b696f916738ce2c"
        }]
    }]
}

The response includes:

Field Description
tracking_id The partner-provided tracking ID, if one was provided.
merchant_id The payer ID of the merchant after creation of their PayPal account.
products An array of statuses for all products that are integrated with the partner for the merchant.
payments_receivable Indicates whether the merchant account can receive payments.
primary_email_confirmed Indicates whether the primary email of the merchant has been confirmed.
primary_email The primary email address of the merchant.
date_created The date when the merchant account was created, in Internet date and time format.
granted_permissions An array of permissions granted to the partner by the merchant.
api_credentials The API credentials of the merchant.
oauth_integrations An array of information about OAuth integrations between partners and merchants.
limitations An array of limitations that are set on the merchant account.

Webhooks

When you send a transaction to PayPal for a merchant who has not completed PayPal account set up, the status of the transaction is pending. PayPal sends a PAYMENT.CAPTURE.PENDING webhook with the Seller_setup_pending reason code.

After the merchant completes PayPal account set up, PayPal sends these webhooks:

  • PAYMENT.CAPTURE.COMPLETED to indicate that the payment capture has changed from pending to completed.
  • MERCHANT.ONBOARDING.COMPLETED to indicate that the merchant has completed account setup. You can subscribe to webhooks to be alerted when a merchant's account setup is complete.

PayPal also sends the MERCHANT.PARTNER-CONSENT.REVOKED webhook when the merchant account is closed, or the account setup consents have been revoked.

For more information about these webhook events, see Webhook event names.

Congratulations

You have completed connected path onboarding.

Next: To add PayPal to your checkout experience, see the Orders Integration Guide.