PayPalCheckout

PayPalCheckout

This class represents a PayPal Checkout component that coordinates with the PayPal checkout.js library. Instances of this class can generate payment data and tokenize authorized payments.

All UI (such as preventing actions on the parent page while authentication is in progress) is managed by checkout.js.

Constructor

new PayPalCheckout(options)

Do not use this constructor directly. Use braintree-web.paypal-checkout.create instead.

You must have PayPal's checkout.js script loaded on your page to use PayPal Checkout. You can either use the paypal-checkout package on npm with a build tool or use a script hosted by PayPal:

<script src="https://www.paypalobjects.com/api/checkout.js" data-version-4 log-level="warn"></script>

Once you have the script loaded, there are two ways to integrate with the checkout.js library.

Pass a Braintree object into checkout.js

You can pass a braintree object into PayPal's checkout.js library. This will create the necessary Braintree client and PayPal Checkout components and automatically tokenize the authorized PayPal account. Use this integration option if you are not integrating with any other Braintree components.

paypal.Button.render({
  braintree: braintree, // this object is available on the window by including the client and paypal-checkout component scripts on the page
  client: {
    production: 'production_authorization',
    sandbox: 'sandbox_authorization'
  },

  env: 'production', // or 'sandbox'

  payment: function (data, actions) {
    return actions.braintree.create({
      // your createPayment options here
    });
  },

  onAuthorize: function (payload, actions) {
    // send payload.nonce to your server

    // for more data about the user's PayPal account:
    // return actions.payment.get().then(function(data) { console.log(data); });
  }
}, '#paypal-button'); // the PayPal button will be rendered in an html element with the id `paypal-button`

If you are using npm to load braintree, simply pass in the invidual components:

var btClient = require('braintree-web/client');
var btPayPal = require('braintree-web/paypal-checkout');

paypal.Button.render({
  braintree: {
    client: btClient,
    paypalCheckout: btPayPal
  },
  client: {
    production: 'production_authorization',
    sandbox: 'sandbox_authorization'
  },
  // rest of checkout.js config

Create the Braintree components manually

Alternatively, you can create the Braintree client and PayPal Checkout components manually. Use this integration style if you prefer to have some logic between receiving the authorized PayPal account and tokenizing it.

braintree.client.create({
  authorization: 'authorization'
}).then(function (clientInstance) {
  return braintree.paypalCheckout.create({
    client: clientInstance
  });
}).then(function (paypalCheckoutInstance) {
  return paypal.Button.render({
    env: 'production', // or 'sandbox'

    payment: function () {
      return paypalCheckoutInstance.createPayment({
        // your createPayment options here
      });
    },

    onAuthorize: function (data, actions) {
      // some logic here before tokenization happens below
      return paypalCheckoutInstance.tokenizePayment(data).then(function (payload) {
        // Submit payload.nonce to your server
      });
    }
  }, '#paypal-button');
}).catch(function (err) {
 console.error('Error!', err);
});
Parameters:
Name Type Description
options object

see paypal-checkout.create

Source:

Methods

createPayment(options, callbackopt) → {Promise|void}

Creates a PayPal payment ID or billing token using the given options. This is meant to be passed to PayPal's checkout.js library. When a callback is defined, the function returns undefined and invokes the callback with the id to be used with the checkout.js library. Otherwise, it returns a Promise that resolves with the id.

Parameters:
Name Type Attributes Description
options object

All options for the PayPalCheckout component.

Properties
Name Type Attributes Default Description
flow string

Set to 'checkout' for one-time payment flow, or 'vault' for Vault flow. If 'vault' is used with a client token generated with a customer ID, the PayPal account will be added to that customer as a saved payment method.

intent string <optional>
authorize
  • authorize - Submits the transaction for authorization but not settlement.
  • order - Validates the transaction without an authorization (i.e. without holding funds). Useful for authorizing and capturing funds up to 90 days after the order has been placed. Only available for Checkout flow.
  • sale - Payment will be immediately submitted for settlement upon creating a transaction.
offerCredit boolean <optional>
false

Offers PayPal Credit as the default funding instrument for the transaction. If the customer isn't pre-approved for PayPal Credit, they will be prompted to apply for it.

amount string | number <optional>

The amount of the transaction. Required when using the Checkout flow.

currency string <optional>

The currency code of the amount, such as 'USD'. Required when using the Checkout flow.

displayName string <optional>

The merchant name displayed inside of the PayPal lightbox; defaults to the company name on your Braintree account

locale string <optional>
en_US

Use this option to change the language, links, and terminology used in the PayPal flow. This locale will be used unless the buyer has set a preferred locale for their account. If an unsupported locale is supplied, a fallback locale (determined by buyer preference or browser data) will be used and no error will be thrown.

Supported locales are: da_DK, de_DE, en_AU, en_GB, en_US, es_ES, fr_CA, fr_FR, id_ID, it_IT, ja_JP, ko_KR, nl_NL, no_NO, pl_PL, pt_BR, pt_PT, ru_RU, sv_SE, th_TH, zh_CN, zh_HK, and zh_TW.

enableShippingAddress boolean <optional>
false

Returns a shipping address object in PayPal#tokenize.

shippingAddressOverride object <optional>

Allows you to pass a shipping address you have already collected into the PayPal payment flow.

Properties
Name Type Attributes Description
line1 string

Street address.

line2 string <optional>

Street address (extended).

city string

City.

state string

State.

postalCode string

Postal code.

countryCode string

Country.

phone string <optional>

Phone number.

recipientName string <optional>

Recipient's name.

shippingAddressEditable boolean <optional>
true

Set to false to disable user editing of the shipping address.

billingAgreementDescription string <optional>

Use this option to set the description of the preapproved payment agreement visible to customers in their PayPal profile during Vault flows. Max 255 characters.

landingPageType string <optional>

Use this option to specify the PayPal page to display when a user lands on the PayPal site to complete the payment.

  • login - A PayPal account login page is used.
  • billing - A non-PayPal account landing page is used.
callback callback <optional>

The second argument is a PayPal paymentId or billingToken string, depending on whether options.flow is checkout or vault. This is also what is resolved by the promise if no callback is provided.

Source:
Example
// this paypal object is created by checkout.js
// see https://github.com/paypal/paypal-checkout
paypal.Button.render({
  // when createPayment resolves, it is automatically passed to checkout.js
  payment: function () {
   return paypalCheckoutInstance.createPayment({
      flow: 'checkout',
      amount: '10.00',
      currency: 'USD',
      intent: 'sale'
    });
  },
  // Add other options, e.g. onAuthorize, env, locale
}, '#paypal-button');

teardown(callbackopt) → {Promise|void}

Cleanly tear down anything set up by create.

Parameters:
Name Type Attributes Description
callback callback <optional>

Called once teardown is complete. No data is returned if teardown completes successfully.

Source:
Examples
paypalCheckoutInstance.teardown();

With callback

paypalCheckoutInstance.teardown(function () {
  // teardown is complete
});

tokenizePayment(tokenizeOptions, callbackopt) → {Promise|void}

Tokenizes the authorize data from PayPal's checkout.js library when completing a buyer approval flow. When a callback is defined, invokes the callback with tokenizePayload and returns undefined. Otherwise, returns a Promise that resolves with a tokenizePayload.

Parameters:
Name Type Attributes Description
tokenizeOptions object

Tokens and IDs required to tokenize the payment.

Properties
Name Type Attributes Description
payerId string

Payer ID returned by PayPal onAuthorize callback.

paymentId string <optional>

Payment ID returned by PayPal onAuthorize callback.

billingToken string <optional>

Billing Token returned by PayPal onAuthorize callback.

callback callback <optional>

The second argument, payload, is a tokenizePayload. If no callback is provided, the promise resolves with a tokenizePayload.

Source:

Type Definitions

tokenizePayload :object

PayPal Checkout tokenized payload. Returned in PayPalCheckout#tokenizePayment's callback as the second argument, data.

Properties:
Name Type Attributes Description
nonce string

The payment method nonce.

type string

The payment method type, always PayPalAccount.

details object

Additional PayPal account details.

Properties
Name Type Attributes Description
email string

User's email address.

payerId string

User's payer ID, the unique identifier for each PayPal account.

firstName string

User's given name.

lastName string

User's surname.

countryCode string <nullable>

User's 2 character country code.

phone string <nullable>

User's phone number (e.g. 555-867-5309).

shippingAddress object <nullable>

User's shipping address details, only available if shipping address is enabled.

Properties
Name Type Description
recipientName string

Recipient of postage.

line1 string

Street number and name.

line2 string

Extended address.

city string

City or locality.

state string

State or region.

postalCode string

Postal code.

countryCode string

2 character country code (e.g. US).

billingAddress object <nullable>

User's billing address details. Not available to all merchants; contact PayPal for details on eligibility and enabling this feature. Alternatively, see shippingAddress above as an available client option.

Properties
Name Type Description
line1 string

Street number and name.

line2 string

Extended address.

city string

City or locality.

state string

State or region.

postalCode string

Postal code.

countryCode string

2 character country code (e.g. US).

creditFinancingOffered object <nullable>

This property will only be present when the customer pays with PayPal Credit.

Properties
Name Type Description
totalCost object

This is the estimated total payment amount including interest and fees the user will pay during the lifetime of the loan.

Properties
Name Type Description
value string

An amount defined by ISO 4217 for the given currency.

currency string

3 letter currency code as defined by ISO 4217.

term number

Length of financing terms in months.

monthlyPayment object

This is the estimated amount per month that the customer will need to pay including fees and interest.

Properties
Name Type Description
value string

An amount defined by ISO 4217 for the given currency.

currency string

3 letter currency code as defined by ISO 4217.

totalInterest object

Estimated interest or fees amount the payer will have to pay during the lifetime of the loan.

Properties
Name Type Description
value string

An amount defined by ISO 4217 for the given currency.

currency string

3 letter currency code as defined by ISO 4217.

payerAcceptance boolean

Status of whether the customer ultimately was approved for and chose to make the payment using the approved installment credit.

cartAmountImmutable boolean

Indicates whether the cart amount is editable after payer's acceptance on PayPal side.

Source: