Build merchant onboarding workflow

1. Load Embedded SDK

PayPal's Embedded SDK provides the necessary pre-built tools to render the embedded merchant onboarding flow on your webpage.

For production environment: https://www.paypalobjects.com/sdk/v1/js/partner.js

For sandbox environment: https://www.paypalobjects.com/sdk/v1/js/sandbox.partner.js

Result: The script introduces a window.Paypal.onboard element for initializing and rendering the merchant onboarding experience.

<script src="https://www.paypalobjects.com/sdk/v1/js/partner.js" defer></script>
<!-- or for sandbox -->
<script src="https://www.paypalobjects.com/sdk/v1/js/sandbox.partner.js" defer></script>

Important information

2. Initialize Embedded SDK

Use the window.Paypal.onboard.initialize() method to create a Partner SDK instance and include the following parameters:

Response: Creates an initialized onboarding instance ready to render the merchant signup experience on your platform.

<script>
  window.Paypal.onboard.initialize({
    accessToken: ACCESS_TOKEN,
    actionUrl: ACTION_URL,
    style: PAYPAL_THEME, // custom styling
    ... // callbacks
  });
</script>

3. Render Embedded SDK

After initializing the Embedded SDK, render the merchant onboarding experience on your webpage.

To render the onboarding experience:

<div id="ELEMENT_ID"></div>
<script>
  window.Paypal.onboard.render('ELEMENT_ID');
</script>

Result: Renders the merchant onboarding experience for your customers.

4. Handle Embedded SDK callbacks

Manage onboarding events and user interactions by using callback functions during Partner SDK initialization.

The Partner SDK supports three main callback types:

Handle errors

In your app code, include the logic to handle errors during the merchant onboarding process. Use the onError() callback function, which receives error and errorInfo parameters. The error parameter contains the error thrown by the component, while errorInfo provides additional context including the componentStack trace.

Response: Processes onboarding-specific errors and provides error details for troubleshooting onboarding failures, including terminal errors after reaching maximum retry attempts.

window.Paypal.onboard.initialize({
  accessToken: 'CLIENT_TOKEN',
  actionUrl: 'ACTION_URL',
  onError: function(error, errorInfo) {
    alert("There is an error\nError: " + error + "\nError Description: \n" + errorInfo);
    window.location.reload();
  }
}).render('root');

Track onboarding status

After initializing the Partner SDK and rendering the onboarding experience, you can code your app to check on the merchant onboarding status in two ways:

Use webhooks

Webhook events are external events your app does not know about unless it receives event notifications. For example, when a merchant account gets created or changes status, this triggers a webhook event.

You can subscribe to such events and register a callback (listener) URL. When the event occurs, PayPal sends a notification to the registered callback URL. You can code your app to complete relevant actions based on the event notification it receives.

To handle webhook events:

For more information, see webhooks overview and webhooks integration guide.

Poll for updates

To check the status of merchant onboarding, you can send periodic GET requests to fetch the merchant status. Contact your PayPal Account Manager for the specific endpoints and implementation details.

After sending the GET request, analyze the response to verify that the required capabilities show an ACTIVE status. The following tables show the capabilities for each product and the possible status values: