Connected Path Upfront Onboarding

Overview

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

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:

  1. You post a PayPal signup link on your website for your sellers.
  2. Sellers fill out PayPal's account linking or creation screens.
  3. Sellers' identities verified through PayPal's Customer Identification Program (CIP).
  4. Sellers link their bank account to their PayPal account.
  5. Sellers confirm their email and are ready to receive payments.

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.

Tip: Try the Upfront Connected Path demo. At the end of the demo, you can view the API History to see request calls and responses.

To use Upfront onboarding, you must integrate the PayPal onboarding mini-browser into your site. This enables sellers to create new PayPal accounts or link existing PayPal accounts to your platform without leaving your experience.

Integration steps

Integrating the onboarding mini-browser requires PayPal for Partners approval.

  1. Before you can integrate Upfront Onboarding, you must set up your development environment. After you get a token that lets you access protected REST API resources, you create sandbox accounts to test your web and mobile apps. For details, see Get Started.

    Then, return to this page to integrate Upfront Onboarding.

  2. Make a Partner Referrals API call.
  3. Display the sign-up form in a mini-browser.
  4. Track seller status.

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.

Request sample

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. PayPal recommends tracking your seller's onboarding progress.
requested_capabilities An 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 and pass at least one account permission as a value for the rest_endpoint_feature.1
web_experience_preference object The preference to customize the web experience of the customer.
collected_consents An 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 An array. Contains the product_name object. An array of PayPal products. Set to EXPRESS_CHECKOUT.
Note:1

The integration_details object defines the integration information. This object contains the rest_third_party_details object, which defines a group of third-party REST properties, including the rest_endpoint_feature object that defines an array of features that the partner can access in PayPal on behalf of the merchant. The merchant grants permission for these features to the partner:

  • PAYMENT. Use PayPal to process the seller's payments and initiate steps to authorize and capture the seller's payments.
  • REFUND. Initiate a refund for a specific transaction.
  • PARTNER_FEE. Automatically deduct the partner's fee from each PayPal transaction before the remaining balance settles to the seller's PayPal account. The fee amount is subject to the seller's agreement with the partner.
  • DELAY_FUNDS_DISBURSEMENT. Hold and release the seller's funds in accordance with partner's policy.
  • READ_SELLER_DISPUTE Share the seller's PayPal dispute data from the PayPal Resolution Center with the partner.
  • UPDATE_SELLER_DISPUTE. Enable the partner to manage PayPal disputes and chargebacks on behalf of the seller. Includes permission to furnish the seller's information and supporting documents to PayPal.
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": {
      "partner_specific_identifiers": [{
        "type": "TRACKING_ID",
        "value": "1506721845"
      }]
    },
    "requested_capabilities": [{
      "capability": "API_INTEGRATION",
      "api_integration_preference": {
        "partner_id": "BSD55M2TSQT72",
        "rest_api_integration": {
          "integration_method": "PAYPAL",
          "integration_type": "THIRD_PARTY"
        },
        "rest_third_party_details": {
          "partner_client_id": "AViNcnTmPaYZ3VltsmWEN3UmogFcZnjKsnqaitDo2cHrEEl1Rlns4GSz36CSUl69q9eADJwEItR0Rq7M",
          "feature_list": [
            "PAYMENT",
            "REFUND",
            "PARTNER_FEE",
            "DELAY_FUNDS_DISBURSEMENT"
          ]
        }
      }
    }],
    "web_experience_preference": {
      "partner_logo_url": "https://example.com/paypal.jpg",
      "return_url": "https://example.com/return",
      "action_renewal_url": "https://example.com/renew-prefill-url"
    },
    "collected_consents": [{
      "type": "SHARE_DATA_CONSENT",
      "granted": true
    }],
    "products": [
      "EXPRESS_CHECKOUT"
    ]
  }'

Response sample

A successful call returns a 201 created status code and these HATEOAS links:

  • A self link that shows the referral data
  • An action_url link that redirects sellers to complete the sign-up process

The action_url expires after its first use. If the seller did not complete the onboarding flow, you can call either GET on the self link to re-initialize the action_url or POST /v1/customer/partner-referrals to create a partner referral.

Note: If you call GET /v1/customer/partner-referrals/{partner_referral_id}, the response returns only user data you have passed in about the seller and not any data the seller might have provided on paypal.com.

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

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.

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

Track seller status

You can track the status of the seller you are onboarding. To track your seller's progress:

  1. Set the TRACKING_ID in the partner_specific_identifier array.
"customer_data": {
  "partner_specific_identifiers": [{
    "type": "TRACKING_ID",
    "value": "1506721845"
  }]
},
  1. To retrieve the merchant ID, call /v1/customer/partners/partner_id/merchant-integrations?tracking_id=1506721845.
  1. Call show seller status to retrieve the onboarding status: /v1/customer/partners/{partner_id}/merchant-integrations/{merchant_id}. This API call does not return user data. It only returns information on whether or not the merchant is onboarded and is eligible to process transactions. You must ensure sellers have confirmed their email address before you can process transactions.

Request sample

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"

Response sample

A successful request returns the HTTP 200 OK status code and a JSON response body that shows referral data. You can process transactions when the response shows:

  • payments_receivable flag is true
  • primary_email_confirmed flag is true
  • oauth_third_party is not blank and has third party permissions
{
  "merchant_id": "CG5RZJV4NR5P4",
  "tracking_id": "1537989077589",
  "products": [
    {
      "name": "EXPRESS_CHECKOUT"
    }
  ],
  "payments_receivable": false,
  "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": "AQ7u3fJkUH4cdCEBidsh5U_F1RQCGjglJQdNEEsXCzvQsGsS5MmC8Dk7_ug_IlkUASJezaGqQxQQfVhQ",
        "scopes": ["https://uri.paypal.com/services/payments/realtimepayment", "https://uri.paypal.com/services/payments/refund", "https://uri.paypal.com/services/payments/payment/authcapture"]
      }
    ]
  }]
}

Next

Create a Checkout button.

Feedback