Build merchant onboarding workflow

CurrentDocs

Last updated: Nov 20th, 11:12pm

After generating your Partner Referral URL and client token, use the Partner SDK to embed PayPal's merchant onboarding experience directly into your platform.

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.

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

Important information

Review SDK security best practices and adjust your implementation accordingly.

Use sandbox URLs for development and testing environments only.

Switch to production URLs when deploying to live environments.

Initialize Embedded SDK

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

accessToken: The browser-safe client token generated from the OAuth API.

actionUrl: The merchant onboarding URL generated from the Partner Referrals API.

style: Optional styling object to customize the onboarding experience appearance. For more information about styling options, see Customize SDK styles.

callbacks: Optional callback functions for handling onboarding events and user interactions. For more information about Partner SDK callbacks, see Handle Partner SDK callbacks.

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

1<script>
2  window.Paypal.onboard.initialize({
3    accessToken: ACCESS_TOKEN,
4    actionUrl: ACTION_URL,
5    style: PAYPAL_THEME, // custom styling
6    ... // callbacks
7  });
8</script>

Render Embedded SDK

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

To render the onboarding experience:

Define the container for the onboarding experience: Include a container element in the HTML file corresponding to the webpage where you want to render the experience. Render the SDK on a dedicated page within your platform's logged-in customer experience. Ensure that the target element is a block-level element.
Render the onboarding experience: Use the window.Paypal.onboard.render() method with your specific block-level element ID. Replace ELEMENT_ID with your specific block-level element id attribute.

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

Result: Renders the merchant onboarding experience for your customers.

Notes:

Onboarding status should be tracked by listening to webhook notifications

You can also send GET requests using the tracking_id from your Partner Referrals API request

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:

onComplete()

onError()

onSDKError()

Handle onboarding completion

Implement logic in your app to handle when the merchant reaches the final page of the onboarding flow. Use the onComplete() callback function to handle completion events. This function runs immediately before the Done page appears, marking the final state of onboarding.

The final state may be any of the following:

Successfully provisioned

More information needed

Uploaded documents pending review

Denied provisioning

Response: Handles completion events when the merchant finishes the onboarding process.

1window.Paypal.onboard.initialize({
2  accessToken: 'CLIENT_TOKEN',
3  actionUrl: 'ACTION_URL',
4  onComplete: function() {
5    alert("Onboard completed!");
6    window.location.href = "https://www.mypartnerwebsite.com/";
7  }
8}).render('root');

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.

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

Handle SDK errors

Add logic to manage SDK-specific errors, such as module federation fetch failures. Use the onSDKError() callback function, which receives error and errorInfo parameters. By default, the SDK displays an error page with a retry button. This callback lets you define the behavior when merchants click the retry button.

Response: This callback handles SDK-specific errors, such as failures when fetching PayPal onboarding components. When errors occur, the SDK displays a default error page with a retry button. This callback defines what happens when merchants click retry.

1window.Paypal.onboard.initialize({
2  accessToken: 'CLIENT_TOKEN',
3  actionUrl: 'ACTION_URL',
4  onSDKError: function(error, errorInfo) {
5    alert("There is an error\nError: " + error + "\nError Description: \n" + errorInfo.componentStack);
6    window.location.reload();
7  }
8}).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

Poll for updates

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:

Review the list of webhook events for merchant onboarding and select the events for your app to subscribe:
- CUSTOMER.MANAGED-ACCOUNT.ACCOUNT-CREATED: Occurs when PayPal creates a merchant account
- CUSTOMER.MANAGED-ACCOUNT.ACCOUNT-STATUS-CHANGED: Occurs when PayPal changes the merchant's verification status
- CUSTOMER.MANAGED-ACCOUNT.ACCOUNT-UPDATED: Occurs when PayPal updates the merchant account data

Subscribe to the selected webhook events through one of the following means:
- PayPal developer account: Log in to your account, go to App details page > Features > Webhooks, and subscribe to webhook events.
- Webhooks management API.

In your server-side app code, define a webhook handler that:
- Listens to the webhook event
- Confirms receipt of the webhook event to PayPal
- Verifies the source of the event notification
- Completes further actions based on event data

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:

Product	Capability
PayPal Branded (PayPal, PayLater, Venmo)	RECEIVE_MONEY
Withdraw to Bank Account	WITHDRAW_MONEY
Card Fields	CUSTOM_CARD_PROCESSING
Vaulting	PAYPAL_WALLET_VAULTING_ADVANCED
Google Pay	GOOGLE_PAY
Apple Pay	APPLE_PAY

Capability status	Description
ACTIVE	Merchant is ready to use this capability.
APPROVED	Merchant cannot use this capability for a short duration.
PENDING/NEED_DATA/IN-REVIEW	Merchant currently cannot use this capability until they provide more data via PayPal
SUSPENDED/REVOKED/DENY/INACTIVE	Merchant cannot use this capability.