Connected Path Upfront Onboarding

Overview

With upfront onboarding, your sellers connect with PayPal before they accept PayPal payments from buyers on your platform.

How it works

Your seller clicks on a sign-up link on your website which redirects them to PayPal for sign up. After completing sign up, your sellers are ready to start taking payment.

Integration steps

Before integrating upfront onboarding, you must complete Partner Onboarding, and you must have an access token. Then, complete the following steps:

  1. Make a Partner Referrals API call.
  2. Add a PayPal sign-up link on your site.
  3. Seller signs up on PayPal.
  4. Redirect the seller back to your site.
  5. Track seller onboarding status.

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.

1. Make a Partner Referrals API call

Call the Partner Referrals API to generate a sign-up link that redirects your sellers to sign up with PayPal. Passing your seller's information during the API call will pre-fill the PayPal sign-up flow with your seller's information.

Note: You can also place a sign-up URL on your site without making an API call. See URL onboarding for an example.

Request sample

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"
    ]
  }'

Tip: PayPal recommends passing a tracking ID in the partner_specific_identifiers field of the customer_data field. You can use this ID to track the status of your seller as they complete onboarding.

Response sample

{
  "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."
  }]
}

A successful call returns a 201 created status. The following HATEOAS links are also returned:

  • A self link. You can make a GET request to this link to retrieve the referral data and to reinitialize the action_url.
  • An action_url link. You can place this link in a button or link tag to redirect your sellers to sign up with PayPal. The action_url expires after its first use. You can reinitialize it by making a GET request to the self link or by making another Partner Referrals API call.

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.

You can place the action_url in a button or link to redirect the seller to PayPal for sign up. Alternatively, you can render the PayPal sign-up flow in a mini-browser by using the following code:

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

3. Seller signs up on PayPal

When your seller is redirected to PayPal, they are prompted to either sign up for a PayPal account or log in to an existing one. This experience varies based on the following:

  • The account type the seller has (Business, Personal, or no account).
  • Intent (Business, Mixed, or Casual Seller)—Intent is set on your account, and you work with your account manager to set it.
Intent Does not have an account Has a Business account Has a Personal account
Business Seller asked to sign up for a PayPal Business account. Seller asked to log in to their Business account. Seller asked to upgrade to a Business account or create one.
Mixed Seller asked to sign up for either a PayPal Business account or Personal Account. Seller asked to log in to their Business account. Seller asked to log in to their Personal account.
Casual Seller Seller asked to sign up for a PayPal Personal account. Seller asked to log in to their Business account. Seller asked to log in to their Personal account.

After your seller signs up or logs in, PayPal asks them to grant you permissions to act on their account on their behalf.

Permissions

The permissions a seller can grant to you depend on the features you specified in the requested_capabilities/api_integration_preference/rest_third_party_details/feature_list field of your Partner Referral API call. If you don't specify that field, the permissions a seller can grant to you are based on the features enabled for your account. You can work with your account manager to determine what features you want enabled.

4. Redirect the seller back to your site

When your seller completes the sign up flow, they are redirected to the return URL you specified in the web_experience_preference field of the Partner Referrals API. If you did not specify a return URL in your API call, then the seller is redirected to the return URL set on your account. You can work with your account manager to set a return URL. If no return URL is set on your account, then the seller is redirected to the PayPal dashboard for their account.

During the redirect, PayPal loads the return URL in your seller's browser and attaches the following query parameters:

Parameter Description
merchantId The unique ID of the seller in your system that you specified in the Partner Referrals API call.
merchantIdInPayPal The payer_id of your seller's PayPal account.
permissionsGranted A Boolean indicating whether the seller granted you the permissions you specified in the Partner Referrals API call.
accountStatus Indicates what kind of account was created. For example, BUSINESS_ACCOUNT if a business account was created.
consentStatus A Boolean indicating whether the seller consented to share their credentials with you.
productIntentID It is set to addipmt.
isEmailConfirmed A Boolean indicating whether the seller has confirmed their email with PayPal.
returnMessage A message containing next steps for the seller to take with PayPal.

Request sample

https://return_url?merchantId=merchantId&merchantIdInPayPal=sellers_payer_id&permissionsGranted=true&accountStatus=BUSINESS_ACCOUNT&consentStatus=true&productIntentID=addipmt&isEmailConfirmed=true&returnMessage=To%20start%20accepting%20payments,%20please%20log%20in%20to%20PayPal%20and%20finish%20signing%20up.

5. Track seller onboarding status

Seller onboarding is complete when the following requirements are met:

  • Seller creates a PayPal account.
  • Seller grants you permission to perform payment.
  • Seller confirms the email address of the account.

To track your seller's status in meeting these requirements, you can make a show seller status call.

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"

This request requires the merchant ID of the seller's PayPal account. To get the Merchant ID, you can read the merchantIdInPayPal query parameter attached to the return URL when the seller is redirected back to your site. You can also query it directly by the tracking ID you specified in the Partner Referrals call by calling GET /v1/customer/partners/partner_id/merchant-integrations?tracking_id={tracking_id}.

Response sample

{
  "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"]
      }
    ]
  }]
}

A successful request returns the HTTP 200 OK status code and a JSON response body that shows referral data. It does not return user data. It only returns information on whether or not the merchant is onboarded and is eligible to process transactions. The seller can process transactions when the response shows:

  • payments_receivable is true
  • primary_email_confirmed is true
  • oauth_third_party contains permissions granted

Webhooks

To track your sellers' onboarding status, you can subscribe to the MERCHANT.ONBOARDING.COMPLETED webhook and the MERCHANT.PARTNER-CONSENT.REVOKED webhook.

  • The MERCHANT.ONBOARDING.COMPLETED is triggered when the seller has met all of the requirements for onboarding.

  • The MERCHANT.PARTNER-CONSENT.REVOKED webhook is triggered when the seller revokes permissions they previously granted to you.

URL Onboarding

You can choose to forgo the API call to the Partner Referrals API and instead place the following sign-up link on your site. Sellers are required to complete all sign-up fields.

Note: Sellers must have a PayPal business account for URL onboarding. Casual sellers are not supported.

Example URL

https://www.paypal.com/us/merchantsignup/partner/onboardingentry?channelId=partner&productIntentId=addipmt&partnerId=your_partner_id&returnToPartnerUrl=your_website_link&integrationType=TO&showPermissions=true&features=PAYMENT,REFUND&partnerLogoUrl=your_website_logo_link&merchantId=your_merchant_id&partnerClientId=partner_client_id
Parameter Description
channelId Set to partner.
partnerId The payer_id of your PayPal account. To find the payer_id of your PayPal account, login to your PayPal account at paypal.com, navigate to My Profile by clicking on the Settings icon, and look for your Merchant account ID in My business info. To find the payer_id of a sandbox account, follow the same instructions on sandbox.paypal.com.
partnerClientId Your client ID.
returnToPartnerUrl The URL you want to redirect your seller to after completing sign up. Not specifying a return URL in this sign-up link follows the same behavior as not specifying a return URL when calling the Partner Referral API.
partnerLogoUrl The URL to retrieve your logo from to be displayed during the onboarding process. Applies only if you're not loading the sign-up flow in a mini-browser. If you do not specify a logo URL in this sign-up link, the logo URL set on your account will be used. You can work with your account manager to set the logo URL on your account.
merchantId The unique ID of the seller in your system.
productIntentId Set to addipmt.
features The permissions a seller grants you to operate on their PayPal account. Not specifying features in this sign-up link follows the same behavior as not specifying the feature_list field when calling the Partner Referrals API.
showPermissions A Boolean that if set to true shows permissions in the onboarding flow.
integrationType The type of integration between you and your sellers. To specify OAUTH_THIRD_PARTY, set to TO.

Next

Add Smart Payment Buttons.

Feedback