Connected Onboarding Integration Guide

Important: PayPal for Marketplaces is a limited-release solution at this time. It 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.

Integrated signup flow

With integrated signup, 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. We created this process to be fast and intuitive so more users are likely to complete it.

Here’s how it works:

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

  • If your merchants do not have a PayPal Business account, they are guided to create one before granting you consent.

Setup options

To implement this setup experience for your merchants, you can use either:

  • API integration. This option is the faster of the two options for your merchants. You can opt to pre-fill the PayPal signup form with merchants’ information that you already have. Your merchants have fewer form fields to fill out, enabling them to set up more quickly. This approach requires calling REST APIs.

  • URL integration. This option requires less set up but requires that your merchants complete all signup fields. You use a URL with static parameters to direct the merchant to PayPal. You do not need to call the REST API to pre-fill information but you might have to whitelist the return URL.

Prerequisites

Before you can use the Connected Onboarding API:

API integration steps

Here’s how to use the API option to onboard your merchants:

1. Required Call the REST API.
2. Required Display the signup form in a mini-browser.

Call the REST API

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

POST /v1/customer/partner-referrals
  • customer_data. Merchant’s personal and business data.

  • requested_capabilities. 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. Customizations for the merchant's signup process.

  • collected_consents. Consents you want to collect from the merchant.

  • products. Select Express Checkout.

PayPal returns:

  • A HATEOAS link that enables you to get the referral data. For example:

    GET "https://api.paypal.com/v1/customer/partner-referrals/ZDM4ZT...
    
  • An action_url to redirect 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 hasn’t completed the onboarding process. To enable merchants to return to the onboarding process, you can use the HATEOAS link or use this 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 Onboarding 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.

Here’s more detail about each partner-referrals parameter:

  • 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 Onboarding API Reference.

  • requested_capabilities

    Defines the capabilities, or types of integrations, you are implementing with a merchant. To call PayPal APIs on behalf of the merchant, specify API_INTEGRATION. 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": "6KFWC9NAZWBY8",
        "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.

  • 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.

    Here’s a web_experience_preference code snippet with fields to set the partner_logo_URL, return_URL, and action_renewal_URL:

    "web_experience_preference": {
      "partner_logo_url": "http://leiphone.qiniudn.com/uploads/2014/05/Paypal.jpg",
      "return_url": "http://example.com/return-from-pre-fill-flow",
      "action_renewal_url": "http://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, as follows:

    "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.

Here’s how:

<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="{PartnerboardingURL&displayMode=minibrowser}" target="PPFrame">Sign up for PayPal</a>

</div>

In this code, replace PartnerboardingURL with your actual onboarding URL. The merchant completes the signup and setup flows and returns to your site.

Additional options

Verify merchant status The merchant confirms their PayPal account and email address.
Get account status To verify the status of the merchant's account:
GET v1/customer/partners/partner_id/merchant-integrations/merchant_id

For more information, see the Onboarding API Reference.

Congratulations

You’ve completed connected path onboarding!

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

URL integration steps

To use the URL option to onboard your merchants:

1. Required Place a PayPal signup URL on your site.
2. Required Whitelist the return URL.
3. Required Confirm your merchant’s email address.
4. Optional but recommended Show your merchant account status.

Place a PayPal signup URL on your site

Add a link or button to your site that directs merchants to create a PayPal account, or to log into an existing PayPal account and configure it to accept payments. In the URL, pass the following parameters:

channelId The channel. Set to partner.
partnerId Your payer ID, which is your PayPal account number.
returnToPartnerUrl The URL to return to your site. You might need to whitelist this URL.
partnerLogoUrl The URL to your logo. Can be displayed during the onboarding process. Applies only if the partner is not using in-context display through a mini-browser.
merchantId The unique ID of the merchant in your system. Required if the partner intends to use REST APIs to show the merchant’s account status.
productIntentId Set to addipmt.
features The list of required features:
  • PAYMENT
  • REFUND
  • DIRECT_PAYMENT
  • POST_TRANSACTIONS
  • PARTNER_FEE
  • DELAY_FUNDS_DISBURSEMENT
  • SWEEP_FUNDS_EXTERNAL_SINK
  • ADVANCED_TRANSACTIONS_SEARCH
  • READ_SELLER_DISPUTE
  • UPDATE_SELLER_DISPUTE
  • REAL_TIME_PAYMENT
  • AUTH_CAPTURE
showPermissions If true, shows permissions in the onboarding flow.
Note: PayPal generates permissions based on the feature list that you specify.
integrationType The type of integration between you and your merchants. To specify OAUTH_THIRD_PARTY, set to TO.

Here’s a sample URL:

https://www.paypal.com/us/merchantsign-up/partner/onboardingentry?
channelId=partner&productIntentId=addipmt&partnerId=XJPHENFGXYG87&
showPermissions=true&returnToPartnerUrl=https://www.YourWebsite.com&
integrationType=TO&features=PAYMENT,REFUND&
partnerLogoUrl=https://www.YourWebsite.com/logo.png&merchantId=tracking_merchant

Whitelist the return URL

You might need to whitelist the URL that you pass to return the merchant to your site.

Confirm your merchant’s email address

Once 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 account status

The following sample call and parameters shows the merchant’s encrypted account number (payer_id) and HATEOAS links that let you access the status of the integration:

GET /v1/customer/partners/partner_id/merchant-integrations?tracking_id=merchant_handle
  • partner_id. Your payer_id.

  • merchant_handle. The ID you created for the merchant when you shared customer data with the call to POST /v1/customer/partner-referrals.

The call returns the merchant ID and a HATEOAS link to access status data for the integration:

{
  "merchant_id": "RH6V5EPUPUW3S",
  "tracking_id": "karricepnoint1",
  "links": [{
    "href": "/v1/customer/partners/XJPHPNFGXYGG6/
    merchant - integrations / RH6V5EPUPUW3S ",
    "rel": "get",
    "method": "GET"
  }]
}

Use the following HATEOAS link, which includes your partner_id and the encrypted ID of the merchant, to obtain the integration data for the specified merchant:

"href": "/v1/customer/partners/XJPHPNFGXYGG6/merchant-integrations/RH6V5EPUPUW3S"

Or, use GET to retrieve the status of the account:

GET /v1/customer/partners/partner_id/merchant-integrations/merchant_id

The response includes:

  • Email address of the merchant (if the merchant has granted permission).

  • Email confirmation status (true or false).

  • List of permissions, if the merchant has granted them.

  • The product for which the merchant has been onboarded (such as Express Checkout).

  • Product status (active or inactive).

  • Whether the merchant has restrictions (true or false) on receiving payments.

For example:

"oauth_integrations": [
  {
    "integration_type": "OAUTH_THIRD_PARTY",
    "integration_method": "PAYPAL",
    "oauth_third_party": [{
      "partner_client_id": "AfqTbhAo7f93X2BQW5l-yYEHYY_C8FDUkiPP_6Cw7P35Cqi78fsWVWXzgRQ",
      "merchant_client_id": "ARS75pLzUWaTt_RFAlFv_0hfOpETq1HK_n49nyuDf4i5dqPBZmDk6X1u9JytrtMGaDExCvKSGCOwRbO",
      "scopes": [
        "https://uri.paypal.com/services/payments/payment/authcapture",
        "https://uri.paypal.com/services/payments/realtimepayment"
      ],
    }]
  }
]

Congratulations

You’ve completed connected path onboarding.

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