marketplaces

Marketplaces Upfront Onboarding for Connected Path

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.

Overview

With Upfront onboarding, you ask your sellers to connect with PayPal before buyers make PayPal payments through your marketplace.

Upfront onboarding allows you to onboard both business sellers with PayPal business accounts and casual sellers with their personal PayPal accounts.

How it works

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.

Note: 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 do this, you'll need to integrate the PayPal onboarding mini-browser into your site. This allows sellers to create new PayPal accounts or link existing PayPal accounts to your marketplace without leaving your experience.

Integration steps

Integrating the onboarding mini-browser requires PayPal for Marketplaces approval and a PayPal REST API access token. See Marketplaces Prerequisites for more information.

  1. Make a Partner Referrals API call.
  2. Display the sign-up form in a mini-browser.

1. Make a Partner Referrals API call

Call the Partner Referrals API to provide your sellers with required PayPal account and permissions fields in the mini-browser.

Sample request

Using your access token, send the following items in the request body to /v1/customer/partner-referrals:

Parameter Type Description
customer_data object The seller's business or personal data required to create an account.
requested_capabilities array, contains the capability object An array of capabilities to enable for the seller.
Important: To call PayPal APIs on the seller's behalf, you must enable the API_INTEGRATION capability.
web_experience_preference object The preference to customize the web experience of the customer.
collected_consents array, contains the legal_consent object An array of all consents to collect from sellers.
Important: If SHARE_DATA_CONSENT is not granted, PayPal does not store customer data.
products array, contains the product_name object An array of PayPal products. Set this to EXPRESS_CHECKOUT.
curl -v -X POST https://api.sandbox.paypal.com/v1/customer/partner-referrals \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "customer_data": {
  "customer_type": "MERCHANT",
  "person_details": {
    "email_address": "customer@example.com",
    "name": {
    "prefix": "Mr.",
    "given_name": "Shashank",
    "surname": "Wankhede",
    "middle_name": "Govind"
    },
    "phone_contacts": [
    {
      "phone_number_details": {
      "country_code": "91",
      "national_number": "9740216087"
      },
      "phone_type": "HOME"
    }
    ],
    "home_address": {
    "line1": "11, outer ring road",
    "state": "Karnataka",
    "city": "Bangalore",
    "country_code": "IN",
    "postal_code": "560103"
    },
    "date_of_birth": {
    "event_type": "BIRTH",
    "event_date": "1987-12-29T23:59:59.999Z"
    },
    "nationality_country_code": "IN",
    "identity_documents": [
    {
      "type": "SOCIAL_SECURITY_NUMBER",
      "value": "ABCDEF34646",
      "partial_value": false,
      "issuer_country_code": "US"
    }
    ]
  },
  "business_details": {
    "phone_contacts": [
    {
      "phone_number_details": {
      "country_code": "91",
      "national_number": "9740216087"
      },
      "phone_type": "FAX"
    }
    ],
    "business_address": {
    "line1": "11, outer ring road",
    "state": "Karnataka",
    "city": "Bangalore",
    "country_code": "IN",
    "postal_code": "560103"
    },
    "business_type": "PROPRIETORSHIP",
    "category": "1004",
    "sub_category": "2025",
    "names": [
    {
      "type": "LEGAL",
      "name": "SHASHANK STORE"
    }
    ],
    "business_description": "Arts and handicrafts",
    "event_dates": [
    {
      "event_type": "ESTABLISHED",
      "event_date": "2009-01-31T13:59:45Z"
    }
    ],
    "website_urls": [
    "https://example.com/mystore/"
    ],
    "annual_sales_volume_range": {
    "minimum_amount": {
      "currency": "USD",
      "value": "2000"
    },
    "maximum_amount": {
      "currency": "USD",
      "value": "3000"
    }
    },
    "average_monthly_volume_range": {},
    "identity_documents": [
    {
      "type": "TAX_IDENTIFICATION_NUMBER",
      "value": "ABCDEF34646",
      "partial_value": false,
      "issuer_country_code": "US"
    }
    ],
    "email_contacts": [
    {
      "email_address": "customer-service@example.com",
      "role": "CUSTOMER_SERVICE"
    }
    ]
  },
  "financial_instrument_data": {
    "bank_details": [
    {
      "nick_name": "Bank of America",
      "account_number": "123405668293",
      "account_type": "CHECKING",
      "currency_code": "USD",
      "identifiers": [
      {
        "type": "ROUTING_NUMBER_1",
        "value": "123456789"
      }
      ]
    }
    ]
  },
  "preferred_language_code": "en_US",
  "primary_currency_code": "USD",
  "referral_user_payer_id": {
    "type": "PAYER_ID",
    "value": "RFYUH2QQDGUQU"
  },
  "partner_specific_identifiers": [
    {
    "type": "TRACKING_ID",
    "value": "ABJSDFO343SD"
    }
  ]
  },
  "requested_capabilities": [
  {
    "capability": "BANK_ADDITION"
  }
  ],
  "web_experience_preference": {
  "partner_logo_url": "https://example.com/logo/",
  "return_url": "https://example.com/",
  "action_renewal_url": "https://example.com/renew/"
  },
  "collected_consents": [
  {
    "type": "SHARE_DATA_CONSENT",
    "granted": true
  }
  ],
  "products": [
  "EXPRESS_CHECKOUT"
  ]
}'

Sample response

A successful call returns a 201 Created status code and a HATEOAS link that shows the referral data and an action_url that redirects sellers to complete the sign-up process.

Note: The HATEOAS link provides you information to code against and to reinitialize an expired action_url as the URL has a one hour expiry.

{
  "links": [
    {
      "href": "https://uri.paypal.com/v1/customer/partner-referrals/ZjcyODU4ZWYtYTA1OC00ODIwLTk2M2EtOTZkZWQ4NmQwYzI3RU12cE5xa0xMRmk1NWxFSVJIT1JlTFdSbElCbFU1Q3lhdGhESzVQcU9iRT0=",
      "rel": "self",
      "method": "GET",
      "description": "The read referral data shared by the partner."
    },
    {
      "href": "https://www.paypal.com/merchantsignup/partner/onboardingentry?token=ZjcyODU4ZWYtYTA1OC00ODIwLTk2M2EtOTZkZWQ4NmQwYzI3RU12cE5xa0xMRmk1NWxFSVJIT1JlTFdSbElCbFU1Q3lhdGhESzVQcU9iRT0=",
      "rel": "action_url",
      "method": "GET",
      "description": "The target web redirect URL for the next action."
    }
  ]
}

2. Display the sign-up form in a mini-browser

Use the returned action_url to redirect users to the PayPal integrated sign-up flow in a mini-browser.

Note: Replace the sample URL here with the one returned in your Partner Referrals call.

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

Sellers click on the link and return to your site upon sign-up completion.

Next

Feedback

Have feedback?

Let us know.