Connected Path Upfront Onboarding

Last updated: April 6th 2022, @ 4:06:12 pm


Overview

With upfront onboarding, your sellers Log in 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 be an approved partner. 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: We must configure your account for the features you want to use before you add them to the payload. Work with your account manager to configure the features you need.

Request sample

curl -v -X POST https://api-m.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"
          ]
        }
      }
    }],
    "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.

Note: To accept Smart Payment Button and credit card payments, you must pass PPCP as the value for the products parameter.

Response sample

{
  "links": [
  {
    "href": "https://api-m.sandbox.paypal.com/v1/customer/partner-referrals/ZjcyODU4ZWYtYTA1OC00ODIwLTk2M2EtOTZkZWQ4NmQwYzI3RU12cE5xa0xMRmk1NWxFSVJIT1JlTFdSbElCbFU1Q3lhdGhESzVQcU9iRT0=",
    "rel": "self",
    "method": "GET",
    "description": "The read referral data shared by the partner."
  },
  {
    "href": "https://api-m.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.
IntentDoes not have an accountHas a Business accountHas a Personal account
BusinessSeller 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.
MixedSeller 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 SellerSeller 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.

Note: Sellers must have a business account to accept alternative payment methods.

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:

ParameterDescription
merchantIdThe unique ID of the seller in your system that you specified in the Partner Referrals API call.
merchantIdInPayPalThe payer_id of your seller's PayPal account.
permissionsGrantedA Boolean indicating whether the seller granted you the permissions you specified in the Partner Referrals API call.
accountStatusIndicates what kind of account was created. For example, BUSINESS_ACCOUNT if a business account was created.
consentStatusA Boolean indicating whether the seller consented to share their credentials with you.
productIntentIDIt is set to addipmt.
isEmailConfirmedA Boolean indicating whether the seller has confirmed their email with PayPal.
returnMessageA 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-m.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 webhook 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.

To see whether your seller has been granted the capability to accept credit card payments, you can subscribe to the merchant integration webhooks:

  • The CUSTOMER.MERCHANT-INTEGRATION.PRODUCT-SUBSCRIPTION-UPDATED webhook is triggered when a product subscription is updated.

  • The CUSTOMER.MERCHANT-INTEGRATION.CAPABILITY-UPDATED webhook is triggered when capabilities to an integration are updated.

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

This URL onboarding example onboards a seller to use the Smart Payment Buttons:

https://www.paypal.com/us/merchantsignup/partner/onboardingentry?channelId=partner&productIntentId=addipmt&partnerId=<var>&lt;Partner-Merchant-ID&gt;</var>&returnToPartnerUrl=<var>&lt;Return-URL&gt;</var>&integrationType=TO&showPermissions=true&features=PAYMENT,REFUND&partnerLogoUrl=<var>&lt;Logo-URL&gt;</var>&merchantId=<var>&lt;Tracking-ID&gt;</var>&partnerClientId=<var>&lt;Partner-Client-ID&gt;</var>

This URL onboarding example onboards a seller to use the Smart Payment Buttons and Custom Card Fields:

https://www.paypal.com/bizsignup/partner/entry?&partnerClientId=<var>&lt;partner_client_id&gt;</var>&partnerId=<var>&lt;partner_payer_id&gt;</var>&partnerLogoUrl=<var>&lt;partner_logo_url&gt;</var>&returnToPartnerUrl=<var>&lt;return_url_for_done_page_button&gt;</var>&product=ppcp&integrationType=FO&features=PAYMENT,REFUND</var></code></pre>
ParameterDescription
channelIdSet to partner.
partnerIdThe 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.
partnerClientIdYour client ID.
returnToPartnerUrlThe 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.
partnerLogoUrlThe 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.
merchantIdThe unique ID of the seller in your system.
productIntentIdSet to addipmt.
featuresThe 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.
showPermissionsA Boolean that if set to true shows permissions in the onboarding flow.
integrationTypeThe type of integration between you and your sellers. To specify OAUTH_THIRD_PARTY, set to TO.

Next

Create a Smart Payment Button.