@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.

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).

Browser Support

This library supports all popular browsers, including IE 11. It provides the same browser support as the JS SDK. Here's the full list of supported browsers.

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