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.

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 make 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

1. Required Call the REST API.
2. Required Display the signup form in a mini-browser.
3. Required Confirm your merchant's email address.
4. Optional Show your merchant's account status.

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.

  • 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. Select 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 to which 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 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 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.

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

"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 onboarding URL. The merchant completes the signup and setup flows and returns to your site.

Confirm your merchant's email address

After the merchants 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

The following sample call and parameters show the merchants encrypted account number (payer_id) and HATEOAS links that you use to access the status of 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 show the account status:

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

The response includes:

  • The payer ID of the merchant, if the merchant has granted permission.
  • The tracking ID of the merchant that you created when you shared customer data.
  • The email confirmation status, which is true or false.
  • A list of permissions, if the merchant has granted them.
  • The product for which the merchant has been onboarded, such as Express Checkout.
  • The product status, which is active or inactive.
  • Whether the merchant has restrictions, true or false, on receiving payments.

For example:

{
  "merchant_id": "T49KQUTWRGKBJ",
  "tracking_id": "Karrisunitrackingid",
  "products": [{

    "name": "EXPRESS_CHECKOUT"
  }],
  "payments_receivable": true,
  "primary_email_confirmed": false,
  "oauth_integrations": [{
    "integration_type": "OAUTH_THIRD_PARTY",
    "integration_method": "PAYPAL",
    "oauth_third_party": [{
      "partner_client_id": "Af1bGDNgFBtbJvzEkG25zt4SoNQQ3ustiLm84GWXxe8nq_HE_0wCQ9SH8M1ScmSBURBIzPiCjr5gu-Dq",
      "merchant_client_id": "AUUGsIswpCCUumSVGkWrK3ZP-i3haGh_zbtygOWfquRgVXIPPQgS44JBYYkZVRz3HgQ2iTOEvRNMXiDV",
      "scopes": [
        "https://uri.paypal.com/services/payments/realtimepayment", "https://uri.paypal.com/services/payments/refund", "https://uri.paypal.com/services/payments/payment/authcapture"
      ]
    }]
  }]
}

Webhooks

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

Once the merchant has completed PayPal account setup, 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.