JavaScript SDK reference

SDKLegacyLast updated: April 17th 2024, @ 4:51:01 pm

Important: This JavaScript SDK documentation uses the legacy HostedFields component. For the new integration that uses CardFields component, see Complete Reference using Card Fields.

Overview

The PayPal JavaScript SDK dynamically exposes objects and methods, based on components you are using. These components are configured in the components query string parameter in the URL you have included in the <script>.

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

Allowed components are:

buttons (default)
marks
hosted-fields
funding-eligibility

Buttons

The payment buttons automatically render all eligible buttons in a single location on your page. See the standard payments integration.

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

`style`

Customize your buttons by passing in the style option.

paypal.Buttons({
  style: {
    layout: 'vertical',
    color:  'blue',
    shape:  'rect',
    label:  'paypal'
  }
}).render('#paypal-button-container');

Layout

Set the style.layout option to determine the button layout when multiple buttons are available:

Value	Description	Layout
`vertical`	Default. Buttons are stacked vertically with a maximum of six buttons. Recommended when: Presenting a dynamic list of payment options on checkout and shopping cart pages. Leveraging Checkout as a full stack payments platform.	Mobile Venmo is available on mobile in U.S. markets only. Web
`horizontal`	Buttons are stacked horizontally with a maximum of two buttons. Recommended when: Placing buttons on a product page, next to the product. Space on the page is limited. Alternative payment options are already provided.	Mobile Venmo is available on mobile in U.S. markets only. Web

Which buttons will I see?

The buttons that display are decided automatically, based on a range of factors, including:

Buyer country
Device type
Funding sources the buyer has opted to see

As a result, each buyer might see a unique combination of buttons. Pay Later offers differ by country and have different buttons. To prevent certain buttons from displaying, see Disable funding in the JavaScript SDK reference.

Color

Set the style.color option to one of these values:

Value	Description	Button
`gold`	Recommended People around the world know us for the color gold and research confirms it. Extensive testing determined just the right shade and shape that help increase conversion. Use it on your website to leverage PayPal’s recognition and preference.
`blue`	First alternative If gold doesn't work for your site, try the PayPal `blue` button. Research shows that people know it is our brand color, which provides a halo of trust and security to your experience.
`silver` `white` `black`	Second alternatives If gold or blue doesn't work for your site design or aesthetic, try the `silver`, `white`, or `black` buttons. Because these colors are less capable of drawing people’s attention, we recommend these button colors as a second alternative.

Shape

Set the style.shape option to one of these values:

Value	Description	Button
`rect`	Recommended The default button shape.
`pill`	A secondary button shape option.

Size

By default, the button adapts to the size of its container element.

To customize the button height, set the style.height option to a value from 25 to 55.
Your button container element must be wide enough for your horizontal payment buttons.

Width

The button has a default max width of 750px, but you can make the button larger. Set style.disableMaxWidth to true. Then, change the max-width value at the container level.

<div id="paypal-button-container" style="max-width:1000px;"></div>

<script>
  paypal.Buttons({
  style: {
    disableMaxWidth: true
  },
}).render('#paypal-button-container');
</script>

Label

Set the style.label option to one of these values:

Value	Description	Button
`paypal`	Recommended The default option. Displays the PayPal logo.
`checkout`	Displays the Checkout button.
`buynow`	Displays the PayPal Buy Now button and initializes the checkout flow.
`pay`	Displays the Pay With PayPal button and initializes the checkout flow.
`installment`	Displays the PayPal installment button and offers a specified number of payments during a payment installment period. Note: The `installment` feature is available only in `MX` and `BR`. Set `style.period` to set the number of payments during the installment period: `BR`: 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 `en_MX`, `MX`: 3, 6, 9, 12

Tagline

Set the style.tagline to false to disable the tagline text:

Note: Set the style.layout to horizontal for taglines.

Value	Description	Button
`true`	Recommended Display tagline text Default.
`false`	Disable tagline text.

`createOrder`

The createOrder parameter sets up the details of the transaction. This parameter is called when the buyer clicks the PayPal button, which launches the PayPal Checkout window where the buyer logs in and approves the transaction on the paypal.com website.

Actions

order - Exposes the create action for creating the order.
payment - Deprecated. Migrate to order and upgrade your integration if using checkout.js.

Frontend (HTML)
Backend (Node.js example)

1<!DOCTYPE html>
2<html>
3  <head>
4    <meta name="viewport" content="width=device-width, initial-scale=1">
5  </head>
6  <body>
7    <!-- Replace "test" with your own sandbox Business account app client ID -->
8    <script src="https://www.paypal.com/sdk/js?client-id=test&currency=USD"></script>
9    <!-- Set up a container element for the button -->
10    <div id="paypal-button-container"></div>
11    <script>
12      paypal.Buttons({
13        createOrder() {
14          return fetch("/my-server/create-paypal-order", {
15            method: "POST",
16            headers: {
17              "Content-Type": "application/json",
18            },
19            body: JSON.stringify({
20              cart: [
21                {
22                  sku: "YOUR_PRODUCT_STOCK_KEEPING_UNIT",
23                  quantity: "YOUR_PRODUCT_QUANTITY",
24                },
25              ]
26            })
27          })
28          .then((response) => response.json())
29          .then((order) => order.id);
30        }
31      }).render('#paypal-button-container');
32    </script>
33  </body>
34</html>

Orders v2 API options:

intent — The intent to either capture the payment immediately or authorize a payment for an order after order creation. The values are:
- CAPTURE — Default. The merchant intends to capture payment immediately after the customer makes a payment.
- AUTHORIZE — The merchant intends to authorize a payment and place funds on hold after the customer makes a payment. Authorized payments are guaranteed for up to three days but are available to capture for up to 29 days. After the three-day honor period, the original authorized payment expires and you must re-authorize the payment. You must make a separate request to capture payments on demand. This intent is not supported when you have more than one purchase_unit within your order.
  See authorize a payment and capture funds later.
purchase_units — Required. An array of purchase units. Each purchase unit establishes a contract between a payer and the payee. Each purchase unit represents either a full or partial order that the payer intends to purchase from the payee. See purchase unit request object definition for additional information.
payment_source — Optionally define the payment_source when creating the order. This can be paypal, a vault token, card information for PCI compliant merchants, or APMs. For more information, see Orders v2 API.

`createSubscription`

Provides a simplified and secure subscription experience. PayPal presents payment types to your buyers automatically, making it easier for them to complete their purchase using methods like Pay with Venmo, PayPal Credit, and credit card payments without reintegration as they are made available.

Pass vault=true and intent=subscription in the JavaScript SDK to set up a subscription, rather than a one-time transaction.

<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&components=buttons&vault=true&intent=subscription"></script>

Finally, implement the createSubscription function that's called when the buyer clicks the PayPal button.

Actions

create — Creates a subscription for your plan and includes the plan ID, subscriber details, shipping, and other details. The plan_id must belong to the client-id configured on the script.

actions.subscription.create options: See the create subscription endpoint for allowed options defined in the request body. Also see create a payment button for the subscription for more examples.

paypal.Buttons({
  createSubscription(data, actions) {
    return actions.subscription.create({
      'plan_id': 'P-2UF78835G6983425GLSM44MA'
    });
  },

  onApprove(data) {
    alert('You have successfully created subscription ' + data.subscriptionID);
  }
}).render('#paypal-button-container');

revise — Updates the subscription which could be in ACTIVE or SUSPENDED status. See upgrade or downgrade a subscription to use the Subscriptions API to make a revision.

paypal.Buttons({
  createSubscription(data, actions) {
    // updatedSubscription, status, and subscriptionId are defined by your code
    if (updatedSubscription && (status === 'ACTIVE' || status === 'SUSPENDED')) {
      // if subscription exists, revise it by chaning the plan id
      return actions.subscription.revise(subscriptionId, {
        "plan_id": "NEW_SUBSCRIPTION_PLAN_ID"
      });
    } else {
      return actions.subscription.create({
        'plan_id': 'P-2UF78835G6983425GLSM44MA'
      });
    }
  },

  onApprove(data) {
    alert('You have successfully created subscription ' + data.subscriptionID);
  }
}).render('#paypal-button-container');

`onApprove`

Captures the funds from the transaction and shows a message to the buyer to let them know the transaction is successful. The method is called after the buyer approves the transaction on paypal.com.

Actions

capture() - Promise returning the order details.

paypal.Buttons({
  createOrder() {
    // This function sets up the details of the transaction, including the amount and line item details.
    return fetch("/my-server/create-paypal-order", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        cart: [
          {
            sku: "YOUR_PRODUCT_STOCK_KEEPING_UNIT",
            quantity: "YOUR_PRODUCT_QUANTITY"
          }
        ]
      })
    });
  },
  onApprove(data) {
    // This function captures the funds from the transaction.
    return fetch("/my-server/capture-paypal-order", {
      method: "POST",
      body: JSON.stringify({
        orderID: data.orderID
      })
    })
    .then((response) => response.json())
    .then((details) => {
      // This function shows a transaction success message to your buyer.
      alert('Transaction completed by ' + details.payer.name.given_name);
    });
  }
}).render('#paypal-button-container');
//This function displays payment buttons on your web page.

For the list of order details you receive from /my-server/capture-paypal-order, see capture payment for order in the Orders API reference.

`onCancel`

When a buyer cancels a payment, they typically return to the parent page. You can instead use the onCancel function to show a cancellation page or return to the shopping cart.

Data attributes

orderId — ID of the order.

paypal.Buttons({
  onCancel(data) {
    // Show a cancel page, or return to cart
  }
}).render('#paypal-button-container');

`onError`

If an error prevents buyer checkout, alert the user that an error has occurred with the buttons using the onError callback:

paypal.Buttons({
  onError(err) {
    // For example, redirect to a specific error page
    window.location.href = "/your-error-page-here";
  }
}).render('#paypal-button-container');

Note: This error handler is a catch-all. Errors at this point are not expected to be handled beyond showing a generic error message or page.

`onInit`/`onClick`

Called when the button first renders. You can use it for validations on your page if you are unable to do so prior to rendering. For example, enable buttons when form validation passes or disable if it fails.

Data attributes

fundingSource — the funding source of the button that was clicked. See the funding sources in the standalone buttons guide.

<p id="error" class="hidden">Click the checkbox</p>
<label><input id="check" type="checkbox" required> Click here to continue</label>

<script>
  paypal.Buttons({

    // onInit is called when the button first renders
    onInit(data, actions)  {

      // Disable the buttons
      actions.disable();

      // Listen for changes to the checkbox
      document.querySelector('#check')
        .addEventListener('change', function(event) {

          // Enable or disable the button when it is checked or unchecked
          if (event.target.checked)  {
            actions.enable();
          } else  {
            actions.disable();
          }
      });
    },

    // onClick is called when the button is clicked
    onClick()  {

      // Show a validation error if the checkbox is not checked
      if (!document.querySelector('#check').checked) {
        document.querySelector('#error').classList.remove('hidden');
      }
    }

  }).render('#paypal-button-container');
</script>

For cases when you need asynchronous validation, see asynchronous validation.

`paypal.Buttons().isEligible`

Commonly used for standalone buttons when you need to check if the funding source is eligible.

// Loop over each funding source / payment method
paypal.getFundingSources().forEach(function(fundingSource) {

  // Initialize the buttons
  var button = paypal.Buttons({
    fundingSource: fundingSource
  });

  // Check if the button is eligible
  if (button.isEligible()) {

    // Render the standalone button for that funding source
    button.render('#paypal-button-container');
  }
});

`paypal.Buttons().render( container )`

Renders the buttons in the defined container selector.

paypal.Buttons().render('#paypal-buttons-container');

`onShippingChange`

While the buyer is on the PayPal site, you can update their shopping cart to reflect the shipping address they chose on PayPal. You can use the callback to:

Validate that you support the shipping address.
Update shipping costs.
Change the line items in the cart.
Inform the buyer that you do not support their shipping address.

Availability: The onShippingChange function is not compatible with Subscriptions.

Data attributes

data: An object containing the buyer’s shipping address. Consists of the following fields:

orderID (required): An ID that represents an order.
paymentID (optional): An ID that represents a payment.
paymentToken (required): An ID/token that represents the resource.
shipping_address (required): The buyer's selected city, state, country, and postal code.
- city: Shipping address city.
- state: Shipping address state or province.
- country_code: Shipping address country.
- postal_code: Shipping address ZIP code or postal code.
selected_shipping_option (optional): Shipping option selected by the buyer.
- label: Custom shipping method label.
- type: Shipping method type (SHIPPING or PICKUP).
- amount: Additional cost for this method.
  - currency_code: ISO currency code (for example, USD).
  - value: String-formatted decimal format (for example, 1.00).

Actions

actions: An object containing methods to update the contents of the buyer’s cart and interact with PayPal Checkout. Consists of the following methods:

resolve: Indicates to PayPal that you do not need to make any changes to the buyer’s cart.
reject: Indicates to PayPal that you will not support the shipping address provided by the buyer.
order: Client-side order API method.
- PATCH: To make the update, pass an array of change operations in the request, as described in the order update API reference. The response returns a promise.

Examples

This example shows not supporting international transactions:

paypal.Buttons({
  onShippingChange(data, actions) {
    if (data.shipping_address.country_code !== 'US') {
      return actions.reject();
    }

    return actions.resolve();
  }
}).render('#paypal-button-container');

This example shows a more complex situation in which a state has free shipping, but flat-rate shipping is the standard for the rest of the US:

paypal.Buttons({
  onShippingChange(data, actions) {
    // Reject non-US addresses
    if (data.shipping_address.country_code !== 'US') {
      return actions.reject();
    }

    // Patch the shipping amount
    return fetch("/my-server/patch-paypal-order", {
      method: "PATCH",
      body: JSON.stringify(
        {
          shippingAddress: data.shipping_address
        })
      })
    .then((response) => response.json());
  }
}).render('#paypal-button-container');

Marks

Use marks when the PayPal buttons are presented alongside other funding sources on the page and the PayPal buttons are shown when the buyer clicks a radio button. See Display other payment methods.

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

paypal.Marks(options)

paypal.Marks().isEligible
paypal.Marks().render( container )

`paypal.Marks().isEligible`

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

Commonly used for standalone buttons when you need to check if the funding source is eligible.

// Loop over each funding source / payment method
paypal.getFundingSources().forEach(function(fundingSource) {

  // Initialize the marks
  var mark = paypal.Marks({
    fundingSource: fundingSource
  });

  // Check if the mark is eligible
  if (mark.isEligible()) {

    // Render the standalone mark for that funding source
    mark.render('#paypal-mark-container');
  }
});

`paypal.Marks().render( container )`

Renders the radio buttons that are passed in container selector.

paypal.Marks().render('#paypal-marks-container');

<!-- Render the radio buttons and marks -->
<label>
  <input type="radio" name="payment-option" value="paypal" checked>
  <div id="paypal-marks-container"></div>
</label>

<label>
  <input type="radio" name="payment-option" value="alternate">
</label>

<div id="paypal-buttons-container"></div>
<div id="alternate-button-container">
  <button>Pay with a different method</button>
</div>

<script>
  // Render the PayPal marks
  paypal.Marks().render('#paypal-marks-container');

  // Render the PayPal buttons
  paypal.Buttons().render('#paypal-buttons-container');

  // Listen for changes to the radio buttons
  document.querySelectorAll('input[name=payment-option]')
    .forEach(function (el) {
      el.addEventListener('change', function (event) {

        // If PayPal is selected, show the PayPal button
        if (event.target.value === 'paypal') {
          document.body.querySelector('#alternate-button-container')
            .style.display = 'none';
          document.body.querySelector('#paypal-buttons-container')
            .style.display = 'block';
        }

        // If alternate funding is selected, show a different button
        if (event.target.value === 'alternate') {
          document.body.querySelector('#alternate-button-container')
            .style.display = 'block';
          document.body.querySelector('#paypal-buttons-container')
            .style.display = 'none';
        }
      });
    });

  // Hide non-PayPal button by default
  document.body.querySelector('#alternate-button-container')
    .style.display = 'none';
</script>

Hosted fields

Use when you want to host your own card fields. See advanced credit and debit card payments for integration guidance.

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

paypal.HostedFields

paypal.HostedFields.isEligible
paypal.HostedFields().render( options )

`paypal.HostedFields.isEligible`

Renders the card fields if there are eligible funding sources.

paypal.HostedFields.isEligible();

`paypal.HostedFields().render( options )`

Renders the card fields in the provided container selector with the specified options.

Options

createOrder (required) — Sets up the details of the order. See createOrder.
onApprove (required) — Approves the order. See onApprove.

fields (required)

Name	Description
`number`	A field for card number. Required.
`expirationDate`	A field for expiration date in `MM/YYYY` or `MM/YY` format. This should not be used with the `expirationMonth` and `expirationYear` properties. Required.
`expirationMonth`	A field for expiration month in `MM` format. Use with the `expirationYear` property.
`expirationYear`	A field for expiration year in `YYYY` or `YY` format. Use with the `expirationMonth` property.
`cvv`	A field for 3- or 4-digit card verification code (like CVV or CID). If you'd like to create a CVV-only payment method nonce to verify a card already stored in your vault, omit all other fields to collect CVV only.
`postalCode`	A field for postal or region code.

styles (optional)
An object that represents CSS that is applied in each hosted field. This object looks similar to CSS. Typically, these styles involve fonts such as font-family or color.
You can also pass the name of a class on your site that contains the styles you'd like to apply. The style properties are automatically pulled off the class and applied to the card fields inputs. This is recommended for input elements only. If using a select for the expiration date, unexpected styling can occur.
Here are the CSS properties that the card fields support. Specify any other CSS on your page and outside of any PayPal configuration. Unsupported properties will fail and put a warning in the console.
- appearance
- color
- direction
- font-family
- font-size-adjust
- font-size
- font-stretch
- font-style
- font-variant-alternates
- font-variant-caps
- font-variant-east-asian
- font-variant-ligatures
- font-variant-numeric
- font-variant
- font-weight
- font
- letter-spacing
- line-height
- opacity
- outline
- margin
- padding
- text-shadow
- transition
- -moz-appearance
- -moz-osx-font-smoothing
- -moz-tap-highlight-color
- -moz-transition
- -webkit-appearance
- -webkit-font-smoothing
- -webkit-tap-highlight-color
- -webkit-transition
  Sample code:
```
paypal.HostedFields.render({
  styles: {
    'input': {
      'font-size': '16pt',
      'color': '#3A3A3A'
    },
    '.number': {
      'font-family': 'monospace'
    },
    '.valid':  {
      'color': 'green'
    }
  },
  fields: {
    number: {
      selector: '#card-number'
    },
    cvv: {
      selector: '#cvv',
      placeholder: '•••'
    },
    expirationDate: {
      selector: '#expiration-date'
    }
  }
});
```

Funding eligibility

By default, the payment buttons automatically render all eligible buttons in a single location on your page.

If your use-case permits, you can render individual, standalone buttons for each supported payment method. For example, render the PayPal, Venmo, PayPal Credit, and alternative payment method buttons on different parts of the checkout page, alongside different radio buttons, or on entirely different pages.

Even with standalone buttons, your integrations take advantage of the eligibility logic the PayPal JavaScript SDK provides, meaning only the appropriate buttons for the current buyer automatically display.

paypal.rememberFunding( fundingSources )
paypal.getFundingSources
paypal.isFundingEligible( fundingSource )

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

`paypal.rememberFunding( fundingSources )`

If a prior funding source was chosen to be remembered by the customer, it is stored for retrieval for future transactions.

paypal.rememberFunding([ paypal.FUNDING.VENMO ]);

`paypal.getFundingSources`

Loop over funding sources and payment methods.

paypal.getFundingSources().forEach(function(fundingSource) {
  // ...
});

`paypal.isFundingEligible( fundingSource )`

Check for funding eligibility from current funding sources.

paypal.isFundingEligible(fundingSource);

Funding

This table includes the available funding sources. By default, the payment buttons automatically render all eligible buttons in a single location on your page. If you need to override this, you can specify the buttons you'd like to show by following the Standalone payment buttons guide.

Funding source	Payment button
`paypal.FUNDING.PAYPAL`	PayPal
`paypal.FUNDING.CARD`	Credit or debit cards
`paypal.FUNDING.CREDIT`	PayPal Credit
`paypal.FUNDING.VENMO`	Venmo
`paypal.FUNDING.SEPA`	SEPA-Lastschrift
`paypal.FUNDING.BANCONTACT`	Bancontact
`paypal.FUNDING.EPS`	eps
`paypal.FUNDING.GIROPAY`	giropay (Legacy) *
`paypal.FUNDING.IDEAL`	iDEAL
`paypal.FUNDING.MERCADOPAGO`	Mercado Pago
`paypal.FUNDING.MYBANK`	MyBank
`paypal.FUNDING.P24`	Przelewy24
`paypal.FUNDING.SOFORT`	Sofort (Legacy) *

* Important: giropay will be sunset on June 30, 2024. PayPal will not support giropay payments starting July 1, 2024. Offer your users PayPal wallet and other alternative payment methods.

* Important: Sofort will be sunset on April 18, 2024. PayPal will not support Sofort payments starting April 19, 2024. Offer your users PayPal wallet and other alternative payment methods. Learn more.

Messages

Use when you want to display Pay Later messages on your site. Because Pay Later offers differ by country, certain options for the messages component render differently depending on country. For complete details, as well as country-specific examples, see Pay Later Reference.

JavaScript SDK reference

Overview

Buttons

paypal.Buttons(options)

style

Layout

Which buttons will I see?

Color

Shape

Size

Width

Label

Tagline

createOrder

Actions

createSubscription

Actions

onApprove

Actions

onCancel

Data attributes

onError

onInit/onClick

Data attributes

paypal.Buttons().isEligible

paypal.Buttons().render( container )

onShippingChange

Data attributes

Actions

Examples

Marks

paypal.Marks(options)

paypal.Marks().isEligible

paypal.Marks().render( container )

Hosted fields

paypal.HostedFields

paypal.HostedFields.isEligible

paypal.HostedFields().render( options )

Options

Funding eligibility

paypal.rememberFunding( fundingSources )

paypal.getFundingSources

paypal.isFundingEligible( fundingSource )

Funding

Messages

See also

`style`

`createOrder`

`createSubscription`

`onApprove`

`onCancel`

`onError`

`onInit`/`onClick`

`paypal.Buttons().isEligible`

`paypal.Buttons().render( container )`

`onShippingChange`

`paypal.Marks().isEligible`

`paypal.Marks().render( container )`

`paypal.HostedFields.isEligible`

`paypal.HostedFields().render( options )`

`paypal.rememberFunding( fundingSources )`

`paypal.getFundingSources`

`paypal.isFundingEligible( fundingSource )`