JS SDK Reference

DocsBetaLast updated: February 13th 2024, @ 10:53:41 am


Query paramDefaultDescription
client-idn/aYour PayPal REST client ID. This identifies your PayPal account and determines where transactions are paid.
componentsbuttonsA comma-separated list of components to enable. The buttons, payment-fields, marks, and funding-eligibility components are required for payment fields components.
enable-fundingnoneFunding sources to allow from showing in the buttons and marks.

By default, PayPal JavaScript SDK provides smart logic to display only appropriate marks and buttons for the current buyer. This optional parameter bypasses the buyer country check for desired payment methods.

For example:

https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&enable-funding=ideal,bancontact

currencyUSDCurrency of the transaction.
localeautomaticBy default, PayPal detects the preferred locale for the buyer based on their geolocation and browser preferences. It is recommended to pass this parameter with a supported locale if you would like the payment fields components to render in the same language as the rest of your site.
intentcaptureThe funds are captured immediately, while the buyer is present on your site.
committrueThis indicates that the final amount won't change after the buyer returns from PayPal to your site.
vaultfalseDisplays all funding sources including those that don’t support vaulting.

paypal.Buttons(options)

style

Customize your buttons by passing in the style option.

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

Note: Alternative payment methods supports only vertical layout.

See additional, optional parameters.

createOrder

The createOrder parameter sets up the details of the transaction. It's 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.

Because this is a client-side call, PayPal calls the Orders API on your behalf, so you don't need to provide the headers and body.

Actions

  • order exposes the create action for creating the order.
<script>
  paypal.Buttons({
    createOrder: function(data, actions) {
      // Set up the transaction
      return actions.order.create({
        purchase_units: [{
          amount: {
            value: '0.01'
          }
        }]
      });
    }
  }).render('#paypal-button-container');
</script>

actions.order.create 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 Alternative Payment Methods do not support intent AUTHORIZE
  • payer The customer who approves and pays for the order. The customer is also known as the payer and buyer. See payer object definition for additional information.

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

  • application_context Customize the payer experience during the approval process for the payment with PayPal. See order_application_context object definition for additional information.

onApprove

The onApprove function is called after the buyer approves the transaction.

Make the capture call from your server to capture the funds from the transaction and show a message to the buyer to let them know the transaction is successful.

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: function (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: function (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 aren't expected to be handled beyond showing a generic error message or page.

paypal.Buttons().isEligible

Before rendering marks and payment fields, you can use paypal.Buttons().isEligible 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');
  }
});

Funding

This table includes the available alternative payment methods.

Funding sourceDescription
paypal.FUNDING.BANCONTACTBancontact
paypal.FUNDING.EPSeps
paypal.FUNDING.GIROPAYgiropay (Legacy) *
paypal.FUNDING.IDEALiDEAL
paypal.FUNDING.BLIKBLIK
paypal.FUNDING.MYBANKMyBank
paypal.FUNDING.P24Przelewy24
paypal.FUNDING.SOFORTSofort (Legacy) *
paypal.FUNDING.APPLEPAYApplePay

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