PayPal

PayPal

This class represents a PayPal component. Instances of this class have methods for launching auth dialogs and other programmatic interactions with the PayPal component.

Constructor

new PayPal(options)

Parameters:
Name Type Description
options object

see paypal.create
Source:

Methods

teardown(callbackopt) → {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:

tokenize(options, callback) → {PayPal~tokenizeReturn}

Launches the PayPal login flow and returns a nonce payload. Only one PayPal login flow should be active at a time. One way to achieve this is to disable your PayPal button while the flow is open.

Parameters:
Name Type Description
options object

All tokenization options for the PayPal 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

Checkout flows only.

  • authorize - Submits the transaction for authorization but not settlement.
  • sale - Payment will be immediately submitted for settlement upon creating a transaction.
offerCredit boolean <optional>
 false

Offers the customer PayPal Credit if they qualify. Checkout flows only.
useraction string <optional>

This option only applies to the "checkout" flow and will have no effect on the "vault" flow.

Changes the call-to-action in the PayPal flow. By default the final button will show the localized word for "Continue" and implies that the final amount billed is not yet known.

Setting this option to commit changes the button text to "Pay Now" and page text will convey to the user that billing will take place immediately.
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.
callback callback

The second argument, data, is a tokenizePayload.
Source:
Example
button.addEventListener('click', function () {
  // Disable the button so that we don't attempt to open multiple popups.
  button.setAttribute('disabled', 'disabled');

  // Because PayPal tokenization opens a popup, this must be called
  // as a result of a user action, such as a button click.
  paypalInstance.tokenize({
    flow: 'vault' // Required
    // Any other tokenization options
  }, function (tokenizeErr, payload) {
    button.removeAttribute('disabled');

    if (tokenizeErr) {
      // Handle tokenization errors or premature flow closure

      switch (tokenizeErr.code) {
        case 'PAYPAL_POPUP_CLOSED':
          console.error('Customer closed PayPal popup.');
          break;
        case 'PAYPAL_ACCOUNT_TOKENIZATION_FAILED':
          console.error('PayPal tokenization failed. See details:', tokenizeErr.details);
          break;
        case 'PAYPAL_FLOW_FAILED':
          console.error('Unable to initialize PayPal flow. Are your options correct?', tokenizeErr.details);
          break;
        default:
          console.error('Error!', tokenizeErr);
      }
    } else {
      // Submit payload.nonce to your server
    }
  });
});

Type Definitions

tokenizePayload :object

Properties:
Name Type 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).
Source:

tokenizeReturn :object

Properties:
Name Type Description
close function

A handle to close the PayPal checkout flow.
focus function

A handle to focus the PayPal checkout flow. Note that some browsers (notably iOS Safari) do not support focusing popups. Firefox requires the focus call to occur as the result of a user interaction, such as a button click.
Source: