Build action widgets

DocsCurrent

Last updated: Oct 6th, 2:57am

To help merchants stay on top of important tasks, you can embed PayPal's action widgets directly into your platform using the Servicing SDK.

Load Embedded SDK

PayPal's Embedded SDK provides the tools to render action widgets on your webpage.

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

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

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

Result: The script introduces the window.PayPal.MONEY element for initializing and rendering the servicing experience.

Important information

Review SDK security best practices and adjust your implementation accordingly.

Use sandbox URLs for development and testing only.

Switch to production URLs when deploying to live environments.

Initialize Embedded SDK

Use the window.PayPal.ACTION_WIDGETS.initialize() method to create an instance of the Servicing SDK and include the following parameters:

payerId: The merchant's spoke account payer ID.

style: Optional styling object to customize the experience.

targetElementId: The ID of the block-level container element where the experience will be rendered.

partnerId: Your partner identifier.

Response: Creates an initialized servicing instance ready to render action widgets on your platform.

1window.PayPal.ACTION_WIDGETS.initialize({
2  targetElementId: 'money-container',
3  payerId: '6A4E4T8774XD5456767',
4  style: {
5    color: {
6      primary: { main: 'red' },
7      secondary: { main: 'green' },
8    },
9  },
10  partnerId: 'BigC'
11});

Render Embedded SDK

After initializing the Embedded SDK, render the servicing experience in your specified container.

Define a block-level container element in your HTML where you want to render the widgets.

Render the SDK within the logged-in customer experience of your platform.

Result: Renders the action widgets for your merchants.

Note: Ensure the target element is a block-level element and is visible within your platform's authenticated experience.

Use action widgets

After you initialize the Embedded SDK, the SDK prompts merchants to log in with their PayPal business account credentials. Merchants complete the login process in a pop-up window.

Note: Logging in to PayPal.com is a temporary solution. We will replace it with an OpenID Connect (OIDC)-based authentication method, allowing merchants to authenticate seamlessly without manual login.

When merchants select an action button on a widget, the platform redirects them to the corresponding flow. For example, when merchants select View Hold, the embedded experience opens an overlay page with details about the hold.

Sample action widgets

The following examples show how different action widgets help merchants manage their accounts:

Complete your profile:

If a merchant has not finished onboarding, the platform displays an action widget that prompts them to complete their profile to start accepting payments. When merchants select Complete your profile the integration redirects them to the onboarding flow at the point where they left off.

Manage Disputes:

The platform displays a disputes widget when merchants have pending disputes on their accounts. Selecting Manage Disputes takes merchants to the disputes experience on the partner website.

View Hold:

When a hold on the merchant's account requires action to release funds, the platform displays a View Hold action widget. This widget helps merchants quickly identify and resolve issues that affect their accounts.