@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

A client-side loader 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=sb"></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.

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

loadScript({ 'client-id': 'sb' })
    .then(paypal => {
        paypal.Buttons().render('#your-container-element');
    });

Setting Options

The options object can be used to set query parameters and script attributes.

Query Parameters

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

loadScript({ 'client-id': '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>

View the full list of supported query parameters.

Data Attributes

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

loadScript({ 'client-id': 'YOUR_CLIENT_ID', 'data-client-token': 'abc123xyz==' });

Which will load the following <script> asynchronously:

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

View the full list of supported script parameters.

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:

1. Use a global polyfill strategy that monkey patches the window.Promise API implementation.
2. 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/dist/paypal.legacy.browser.min.js"></script>

Using a CDN

The paypal-js script is also available on the unpkg CDN. The paypal.browser.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/dist/paypal.browser.min.js"></script>
    </head>
    <body>
        <div id="paypal-buttons"></div>
        <script>
            window.paypalLoadScript({ 'client-id': 'sb' })
                .then(paypal => {
                    paypal.Buttons().render('#paypal-buttons');
                });
        </script>
    </body>
</html>

Note that the above CDN location points to the latest release of paypal-js. It is advised that when you deploy your site, you import the specific version you have developed and tested with (ex: https://unpkg.com/@paypal/paypal-js@1.0.0/dist/paypal.browser.min.js).

Releasing

Run one of the following commands to publish a new version to npm:

# bug fixes
npm run release:patch

# new functionality that's backwards compatible
npm run release:minor

# breaking changes
npm run release:major