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 sellers so they can accept PayPal payments.

New Progressive onboarding: Enables buyers to easily pay with PayPal for all sellers, even those sellers who do not yet have PayPal accounts. Sellers 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 sellers and PayPal handles the rest. This signup flow uses an in-context experience to keep your sellers 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 sellers already have a PayPal account, the sellers 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 sellers do not have a PayPal account, they are prompted to create one, after which they can grant you consent.

To implement this setup experience for your sellers, you can integrate with our partner-referrals API, which enables you to pre-fill the PayPal signup form with information you already have. Your sellers 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 sellers complete all signup fields. You use a URL with static parameters to direct the seller 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:

  • Learn about the PayPal REST API.
  • Get a account. Partners must have a PayPal account and be approved to use it in order to integrate their Marketplace. Speak to your Account Manager for details or contact us.

    Note: Your sellers can use a business or personal PayPal account. If your marketplace requires a business account, sellers are provided the opportunity to upgrade their existing personal PayPal account to a business account during onboarding.

  • Register your PayPal marketplace.
  • Learn about HTTP request headers.
  • Receive onboarding-complete Webhooks by making sure that setup is complete

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 seller confirms their email address.
4. Optional Show your seller'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 seller has confirmed their email and granted permissions to their account.

Note: sellers in all countries other than the US must grant permissions to the partner. sellers 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 seller'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 seller integrates with you. To call PayPal APIs on the seller's behalf, you must enable the API_INTEGRATION capability.

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

  • collected_consents. The consents to collect from the seller.

  • 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 seller to complete the signup process.

To help prevent data theft and potential misuse, the URL expires after the first use, even if the seller has not completed the onboarding process. To enable sellers 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 seller:

  • 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 seller'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 seller. API_INTEGRATION enables you to call PayPal APIs on behalf of the seller. 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 seller. Based on the features that you specify, PayPal generates and assigns a set of API permissions to you. During the setup flow, the seller 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 seller oriented to your site. 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 seller to leverage the pre-fill feature. To indicate that the seller 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 seller uses. Currently, Express Checkout is the only PayPal product for which you can onboard a seller.

"products": [
  "EXPRESS_CHECKOUT"
]

Display the signup form in a mini-browser

The action URL links to the PayPal integrated signup flow. When sellers click the link, they go through the signup process with the seller 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 sellers:

<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 seller completes the signup and setup flows and returns to your site.

Your seller confirms their email address

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

Note: During the ISU onboarding, the seller needs to confirm email. Transactions for accounts with unconfirmed email will be voided.

Show your seller's account status

To show status information for sellers who were onboarded by a partner, include the ID of the partner and the ID of the seller 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 seller after creation of their PayPal account.
products An array of statuses for all products that are integrated with the partner for the seller.
payments_receivable Indicates whether the seller account can receive payments.
primary_email_confirmed Indicates whether the primary email of the seller has been confirmed.
primary_email The primary email address of the seller.
date_created The date when the seller account was created, in Internet date and time format.
granted_permissions An array of permissions granted to the partner by the seller.
api_credentials The API credentials of the seller.
oauth_integrations An array of information about OAuth integrations between partners and sellers.
limitations An array of limitations that are set on the seller account.

Webhooks

When you send a transaction to PayPal for a seller 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 seller 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 seller has completed account setup. You can subscribe to webhooks to be alerted when a seller's account setup is complete.

PayPal also sends the MERCHANT.PARTNER-CONSENT.REVOKED webhook when the seller 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.