@paypal/paypal-js

What is @paypal/paypal-js?

@paypal/paypal-js is an npm package that provides a client-side JavaScript SDK for integrating PayPal's payment services into web applications. It allows developers to easily add PayPal buttons, handle transactions, and manage payment flows with minimal setup.

What are @paypal/paypal-js's main functionalities?

Load PayPal Script

This feature allows you to load the PayPal JavaScript SDK dynamically. You need to provide your PayPal client ID, and the script will be loaded asynchronously.

import { loadScript } from '@paypal/paypal-js';

loadScript({ 'client-id': 'your-client-id' }).then((paypal) => {
  console.log('PayPal script loaded successfully');
}).catch((error) => {
  console.error('Failed to load PayPal script', error);
});

Render PayPal Buttons

This feature allows you to render PayPal buttons on your web page. You can customize the button's behavior, such as creating an order and handling the approval process.

import { loadScript } from '@paypal/paypal-js';

loadScript({ 'client-id': 'your-client-id' }).then((paypal) => {
  paypal.Buttons({
    createOrder: (data, actions) => {
      return actions.order.create({
        purchase_units: [{
          amount: {
            value: '0.01'
          }
        }]
      });
    },
    onApprove: (data, actions) => {
      return actions.order.capture().then((details) => {
        alert('Transaction completed by ' + details.payer.name.given_name);
      });
    }
  }).render('#paypal-button-container');
});

Handle Payment Transactions

This feature allows you to handle payment transactions, including creating orders, capturing payments, and handling errors during the transaction process.

import { loadScript } from '@paypal/paypal-js';

loadScript({ 'client-id': 'your-client-id' }).then((paypal) => {
  paypal.Buttons({
    createOrder: (data, actions) => {
      return actions.order.create({
        purchase_units: [{
          amount: {
            value: '0.01'
          }
        }]
      });
    },
    onApprove: (data, actions) => {
      return actions.order.capture().then((details) => {
        console.log('Transaction completed by ' + details.payer.name.given_name);
      });
    },
    onError: (err) => {
      console.error('An error occurred during the transaction', err);
    }
  }).render('#paypal-button-container');
});

Other packages similar to @paypal/paypal-js

react-paypal-button-v2

react-paypal-button-v2 is a React component wrapper for the PayPal JavaScript SDK. It simplifies the integration of PayPal buttons in React applications. Compared to @paypal/paypal-js, it is more tailored for React developers and provides a more seamless integration with React's component-based architecture.

paypal-rest-sdk

paypal-rest-sdk is a server-side SDK for integrating PayPal's REST APIs. It allows you to handle payments, subscriptions, and other PayPal services on the server side. Unlike @paypal/paypal-js, which is client-side, paypal-rest-sdk is used for backend integrations.

braintree-web

braintree-web is a client-side JavaScript SDK for integrating Braintree's payment services, which is a PayPal company. It supports various payment methods, including PayPal. Compared to @paypal/paypal-js, braintree-web offers a broader range of payment options and is suitable for developers looking to integrate multiple payment methods.

README

paypal-js

Loading wrapper and TypeScript types for the PayPal JS SDK

Why use paypal-js?

The default JS SDK code snippet blocks page rendering:

<script src="https://www.paypal.com/sdk/js?client-id=test"></script>
<script>
    paypal.Buttons().render("body");
</script>

The above snippet can be difficult to implement in a non-blocking way, especially in single page web apps. This is where the paypal-js library comes in. It provides the following benefits over the above snippet:

• Async script loading to ensure page rendering isn't blocked.
• A Promise API to know when script loading is complete.
• A convenient way to reload the script when query parameters or data attributes change.

Installation

To get started, install paypal-js with npm.

npm install @paypal/paypal-js

Usage

Import the loadScript function for asynchronously loading the Paypal JS SDK.

loadScript(options)

• accepts an object for passing query parameters and attributes to the JS SDK.
• returns a Promise that resolves with window.paypal after the JS SDK is finished loading.

Async/Await

import { loadScript } from "@paypal/paypal-js";

let paypal;

try {
    paypal = await loadScript({ clientId: "test" });
} catch (error) {
    console.error("failed to load the PayPal JS SDK script", error);
}

if (paypal) {
    try {
        await paypal.Buttons().render("#your-container-element");
    } catch (error) {
        console.error("failed to render the PayPal Buttons", error);
    }
}

Promises

import { loadScript } from "@paypal/paypal-js";

loadScript({ clientId: "test" })
    .then((paypal) => {
        paypal
            .Buttons()
            .render("#your-container-element")
            .catch((error) => {
                console.error("failed to render the PayPal Buttons", error);
            });
    })
    .catch((error) => {
        console.error("failed to load the PayPal JS SDK script", error);
    });

Passing Arguments

The loadScript function accepts an object for configuring the JS SDK. It's used for setting query parameters and script attributes. It accepts parameters in camelCase or kebab-case.

Query Parameters

The following example adds client-id and currency as query string parameters:

loadScript({ clientId: "YOUR_CLIENT_ID", currency: "EUR" });

Which will load the following <script> asynchronously:

<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&currency=EUR"></script>

By default, the JS SDK only loads the buttons component. The components query string parameter can be used to load multiple components:

loadScript({
    clientId: "YOUR_CLIENT_ID",
    components: ["buttons", "marks", "messages"],
});

Which will load the following <script> asynchronously:

<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&components=buttons,marks,messages"></script>

View the full list of supported query parameters.

Data Attributes

All options prefixed with data are considered attributes. The following example adds data-page-type as an attribute:

loadScript({
    clientId: "YOUR_CLIENT_ID",
    dataPageType: "checkout",
});

Which will load the following <script> asynchronously:

<script
    data-page-type="checkout"
    src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID"
></script>

View the full list of supported script parameters.

Merchant Id Array

The merchantId option accepts an array to simplify the implementation for Multi-Seller Payments. With this approach the caller doesn't have to worry about managing the two different merchant id values (data-merchant-id and merchant-id).

Here's an example with multiple merchantId values:

loadScript({
    clientId: "YOUR_CLIENT_ID",
    merchantId: ["123", "456", "789"],
});

Which will load the following <script> and use merchant-id=* to properly configure the edge cache:

<script
    data-merchant-id="123,456,789"
    src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&merchant-id=*"
></script>

Here's an example with one merchant-id value:

loadScript({
    clientId: "YOUR_CLIENT_ID",
    merchantId: ["123"],
});

When there's only one, the merchant-id is passed in using the query string.

<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&merchant-id=123"></script>

sdkBaseUrl

For local development, the sdkBaseUrl option can be used to set the base url of the JS SDK:

loadScript({
    clientId: "YOUR_CLIENT_ID",
    sdkBaseUrl: "http://localhost.paypal.com:8000/sdk/js",
});

Legacy Browser Support

This library relies on JavaScript Promises. To support legacy browsers like IE 11, you must provide your own Promise polyfill. With a Promise polyfill this library will support the same browsers as the JS SDK.

The loadScript() function takes in a second parameter for providing a Promise ponyfill. It defaults to the global Promise object if it exists. There are two options for polyfilling the Promise object:

• Use a global polyfill strategy that monkey patches the window.Promise API implementation.
• Use a ponyfill strategy that passes a Promise library into loadScript() without affecting other code:

import { loadScript } from "@paypal/paypal-js";
import PromisePonyfill from "promise-polyfill";

loadScript(options, PromisePonyfill).then((paypalObject) => {});

We also provide a legacy build that includes the promise-polyfill library. You can reference it from the CDN here:

<script src="https://unpkg.com/@paypal/paypal-js@8.0.0/dist/iife/paypal-js.legacy.min.js"></script>

Using a CDN

The paypal-js script is also available on the unpkg CDN. The iife/paypal-js.js build assigns the loadScript function to the window object as window.paypalLoadScript. Here's an example:

<!doctype html>
<html lang="en">
    <head>
        <script src="https://unpkg.com/@paypal/paypal-js@8.0.0/dist/iife/paypal-js.min.js"></script>
    </head>
    <body>
        <div id="paypal-buttons"></div>
        <script>
            window.paypalLoadScript({ clientId: "test" }).then((paypal) => {
                paypal.Buttons().render("#paypal-buttons");
            });
        </script>
    </body>
</html>

loadCustomScript(options)

The loadCustomScript function is a generic script loader function that works with any url.

• accepts an object for defining the script url and attributes.
• returns a promise to indicate if the script was successfully loaded.

Async/Await

import { loadCustomScript } from "@paypal/paypal-js";

try {
    await loadCustomScript({
        url: "https://www.example.com/index.js",
        attributes: {
            id: "custom-id-value",
            "data-foo": "custom-data-attribute",
        },
    });

    console.log("successfully loaded the custom script");
} catch (error) {
    console.error("failed to load the custom script", error);
}

Promises

import { loadCustomScript } from "@paypal/paypal-js";

loadCustomScript({
    url: "https://www.example.com/index.js",
    attributes: { id: "custom-id-value", "data-foo": "custom-data-attribute" },
})
    .then(() => {
        console.log("successfully loaded the custom script");
    })
    .catch((err) => {
        console.error("failed to load the custom script", err);
    });

TypeScript Support

This package includes TypeScript type definitions for the PayPal JS SDK. This includes types for the window.paypal namespace. We support projects using TypeScript versions >= 3.8.

V6 TypeScript Types

In addition to the type definitions above, this package also includes Typescript type definitions for the PayPal JS SDK V6.

Importing and Using V6 Types

A basic example showing data-typing for PayPal One Time Payment.

import type {
    PayPalV6Namespace,
    CreateInstanceOptions,
    OnApproveDataOneTimePayments,
    OnShippingAddressChangeData,
    SdkInstance
} from "@paypal/paypal-js/sdk-v6";

declare global {
    interface Window {
        paypal?: PayPalV6Namespace | null;
    }
}

const createInstanceOptions: CreateInstanceOptions = {
    clientToken,
    components: ["paypal-payments", "venmo-payments"]
}

const sdkInstance = await window.paypal.createInstance(createInstanceInputs);

function onApproveCallback(data: OnApproveDataOneTimePayments) {}
function onShippingAddressChangeCallback(data: OnShippingAddressChangeData) {}

const paypalCheckout = sdkInstance.createPayPalOneTimePaymentSession({
    onApprove: onApproveCallback,
    onShippingAddressChange: onShippingAddressChangeCallback,
});

Releasing

Run npm run release to publish a new release. The version number is determined by the git commits which follow conventional commits spec.