Merchant Onboarding SDK

This SDK simplifies the integration of merchant onboarding workflows into any application that uses the SDK package. It provides a set of tools and utilities to manage the onboarding process, including:

Table of Contents

• Getting Started
  • Installation
  • Usage
• Onboarding SDK Reference
  • Install Onboarding SDK
  • Initialize Onboarding SDK
    • Onboarding Props Reference
  • Render Onboarding SDK
  • Cleanup Onboarding SDK
• Servicing SDK Reference
  • Install Servicing SDK
  • Initialize and Render Servicing SDK
    • Supported Modules
    • Servicing Props Reference
• Styling Options

Getting Started

Installation

Install the SDK

npm install @paypal/merchant-onboarding-sdk

Usage

1. Add sdk package to your UI element

import { onboard } from "@paypal/merchant-onboarding-sdk/onboarding";

OR

import { servicing } from "@paypal/merchant-onboarding-sdk/servicing";

Disclaimer: There may be side-effects of rendering both onboarding and servicing concurrently due to conflicts in the auth sessions of each

Usage NOTE

If you use SSR, import the script only in the UI as it relies on client-side global objects like window

Example:

import {
    Onboard,
    OnboardOptions,
} from "@paypal/merchant-onboarding-sdk/onboarding";

const [onboard, setOnboard] = useState<Onboard>(null as unknown as Onboard);

useEffect(() => {
    const initSdk = async () => {
      const onbPackage = await import(
        "@paypal/merchant-onboarding-sdk/onboarding"
      );
      setOnboard(onbPackage.default as unknown as Onboard);
    };
    initSdk();
}, []);

useEffect(() => {
    if (onboard) {
      onboard.initialize({ // props }).render("elementId")
    }
}, [onboard])

2. initialize sdk in your app and render

onboard
    .initialize({
        env: 'production', // required for node_module integrations only
        accessToken: 'A21_A.AAdU_t4bpoqBrSPWCvZWX7px-4feNn6Ap1Ixon9zgB46GNnibPWM_GrYcwTUBou-8LUM1WSOP5-XUecATSod2E1x-eoYPA',
        actionUrl: 'https://www.paypal.com/bizsignup/partner/entry?referralToken=ZjRmMTdiNjItMDhlNi00ZjJiLTk3ODAtNTQ0NzE3YjI5MTRkQ3pncW5vYlZpaEZOUnpmc082bTRVekphRENVcy9iWjJmWUt1b3l3TWNidz12Mg==',
        cancelUrl: 'http://www.partner.com/cancelUrl' // add partner's app url
        style: {
            color: {
                background: {
                    highContrast: '#48484a', // font color
                },
                primary: {
                    main: '#1b75bc', //header & button
                    mainHover: '#1871b6',
                    mainActive: '#204d74', // button color after you click
                },
            },
        },
        onError: async function (error,errorInfo) {
            alert("There is an error\nError: " + error +"\nError Description: \n"+ errorInfo)
            window.location.reload()
        },
        onSDKError: async function (error,errorInfo) {
            alert("There is an error\nError: " + error +"\nError Description: \n"+ errorInfo.componentStack)
            window.location.reload()
        },
        onProgress: async function (progress) {},
        onComplete: async function () { alert("Onboard completed!!")},
        onAccessTokenExpiry: async function () {},
        onReferralTokenExpiry: async function () {},
        onCancel: async function () {alert("User cancelled the onboarding")},
        onContactUs: async function () {}
        onLoginRequested: async function (spokePayerId) { return await getToken()} // STANDALONE_HYBRID partners only
    })
    .render('root')

Onboarding SDK Reference

Install Onboarding SDK

import { onboard } from "@paypal/merchant-onboarding-sdk/onboarding";

Initialize Onboarding SDK

Paypal.onboard.initialize(props)

Onboarding Props Reference

| Parameter | Type | Description | Required | | ----------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- | | accessToken | string | The access token for authentication. | Yes | | env | string | The env that should be used. Possible values are 'production' or 'sandbox' | No (defaults to 'production' for npm integrations) | | actionUrl | string | The URL containing the referralToken. | Yes | | cancelUrl | string | The URL to return from onboarding on cancel. | No | | style | object | Styling options (see below). | No | | onProgress | function | Async Callback function that receives a progress object (structure TBD). | No | | onComplete | function | Async Callback function invoked when onboarding completes successfully. | No | | onAccessTokenExpiry | function | Async Callback function invoked when the access token expires. The partner should refresh the token and provide a new actionUrl. | No | | onReferralTokenExpiry | function | Async Callback function invoked when the referral token expires. The partner should refresh the token and provide a new actionUrl. | No | | onCancel | function | Async Callback function invoked when the user cancels onboarding. | No | | onError | function | Async Callback function invoked when an error occurs during onboarding. Receives error and errorInfo objects. | No | | onSDKError | function | Async Callback function invoked for SDK-specific errors. Receives error and errorInfo objects. | No | | onContactUs | function | Async Callback function to display contact information when appropriate. | No | | onLoginRequested | function | Async Callback function to fetch access token for STANDALONE_HYBRID merchant. | Yes (only for spoke-only partners) | | onAccountCreated | function | Async Callback function for client to fetch payer id for linked hybrid accounts. | No (only for linked-hybrid accounts | | onAccountAvailable | function | Async callback (payerId, trackingId) when the linked-hybrid account is available after embedded onboarding (e.g. popup closes). | No (linked-hybrid only) | | ) |

Render Onboarding SDK

Paypal.onboard.render(<containerId>)

containerId is the id of the html container to render the onboarding flow

Example

To render Onboarding in the following div:

<div id="container"></div>

Render the SDK like:

Paypal.onboard.render('container')

Cleanup Onboarding SDK

Paypal.onboard.cleanup()

Unmounts the rendered onboarding component from the DOM and logs out the current merchant session. Call this method whenever you want to remove the onboarding UI from the DOM.

Servicing SDK Reference

Install Servicing SDK

import { servicing } from "@paypal/merchant-onboarding-sdk/servicing";

Initialize And Render Servicing SDK

PayPal.servicing.<MODULE_NAME>.initialize(props)

servicing.ACTION_WIDGETS.initialize({
        targetElementId: 'container',
        getAccessToken: async () => { // implementation here to get spoke access token} ,
        style: {
          color: {
            primary: {
              main: 'red',
            },
            secondary: {
              main: 'green',
            },
          },
        },
        partnerName: 'partner',
        partnerHostedModuleUrls: {
          MONEY: 'www.partner.com/balance', // Partner web url where money SDK is used
          ACTION_WIDGETS: 'www.partner.com/notification' // Partner web url where action widget SDK is used
        }
      });

Supported modules

| Supported Module Names | | ------------------------------------ | | MONEY | | BANKS | | ACTION_WIDGETS | | PAID_FEATURES | | PHONE | | LIFT_LIMITS | | LANGUAGE_EDIT | | TIMEZONE_EDIT | | INSIGHTS | | REPORT | | PAYMENT_PREFERENCES | | VIEW_BUSINESS_PROFILE | | CSM | | ACCOUNT_SETTINGS_PAYMENT_PREFERENCES | | MERCHANT_LISTING | | ACTIVITY_REFUND | | WORKING_CAPITAL |

Servicing Props Reference

| Parameter | Type | Description | Required | | ------------------------- | ---------- | -------------------------------------------------------------------------- | -------------------------------------------------- | | targetElementId | string | The id of the HTML container to render the Servicing SDK | Yes | | getAccessToken | function | Async Callback function that returns spoke account access token | Yes | | env | string | The env that should be used. Possible values are 'sandbox' or 'production' | No (defaults to 'production' for npm integrations) | | partnerName | string | The Partner's name | No | | partnerHostedModuleUrls | object | The URL to return from onboarding on cancel. | No | | style | object | Styling options (see below, same as onboarding). | No |

Styling Options

Paypal makes use of tokens that consist of values needed to construct and maintain a design system, such as spacing, color, size, space, motion, etc. Styles can be passed using these tokens and Paypal will override its Theme with the tokens passed using vanilla-extract.

To override with specific styles just add the style object to the props in onboard.initialize({}) as shown in Initialize and Render

The Style object takes the format of a vanilla-extract Theme: https://vanilla-extract.style/documentation/theming/