JavaScript v2

PayPalanchor

Optionsanchor

The PayPal functionality of Braintree.js accepts a few different options. The below options can be used for all PayPal integration types (Vault, Checkout with PayPal).

important

If you are using a custom or dropin setup, you must specify paypal as its own object and nest the following configuration under it. For an example, see our Drop-in guide.

Client option Description
containerRequired

The id, native DOM element, or jQuery object specifying where on your page the PayPal button should be placed.

paymentMethodNonceInputField

The ID, native DOM element, or jQuery object specifying an input field that the client will write the resulting nonce once the customer has authenticated with PayPal. By default, Braintree.js will insert the following field:

HTML
<input type="hidden" name="payment_method_nonce" />
displayNameString

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

singleUseBoolean

Defaults to false, but can be set to true to trigger the Checkout flow.

intentString

Applies to Checkout flows (singleUse: true). Only available in versions 2.25.0 and higher.


onUnsupportedFunction

A callback function that is fired for any error that can occur during the PayPal flow (e.g. if the customer's browser does not support the Checkout flow). This callback is not available in the Drop-in UI.

onCancelledFunction

A callback function that is fired when the customer clicks the "Cancel" button rendered on your page after successfully completing the PayPal flow. This callback is not available in the Drop-in UI.

onSuccessDeprecated
Function

A callback function that is fired immediately after a user has logged in to PayPal; it is not fired upon form submission like onPaymentMethodReceived. This callback should only be used as a hook to signify that a user has successfully completed the PayPal login flow.


Caveats
  • It is not fired in Drop-in integrations.
  • It is only fired for PayPal logins.
  • It is not fired upon form submission.
  • Its payload data may be in a different format than the data returned by other callbacks.
  • You can get more data that reflects the latest capabilities of our integration by using onPaymentMethodReceived instead.
onAuthorizationDismissedFunction

A callback function that is fired when the customer cancels or closes out of the PayPal flow before successful completion. This is available in versions 2.18.0 and above. This callback is not available in the Drop-in UI.

enableShippingAddressBoolean

Returns a shipping address object in the onPaymentMethodReceived callback under the details object with the following properties:

  • recipientName (String)
  • streetAddress (String)
  • extendedAddress (String)
  • locality (String)
  • region (String)
  • postalCode (String)
  • countryCodeAlpha2 (String)
shippingAddressOverrideObject

Allows you to pass a shipping address you have already collected into the PayPal payment flow. Full examples on Vault and Checkout pages. You can pass in the following parameters:

  • recipientName (String)
  • streetAddress (String)
  • extendedAddress (String)
  • locality (String)
  • countryCodeAlpha2 (String)
  • postalCode (String)
  • region (String)
  • phone (String)
  • editable (Boolean) - true allows customer to choose a different shipping address than what was passed in. false does not allow the customer to edit the shipping address.
enableBillingAddressBoolean

Required to retrieve a billingAddress object for customers paying with PayPal and to have the PayPal Billing Address Request feature enabled in your PayPal account. Not available to all merchants; contact PayPal for details on eligibility and enabling this feature. Alternatively, see enableShippingAddress above as an available client option.

Returns a billing address object in the onPaymentMethodReceived callback under the details object with the following properties:

  • streetAddress (String)
  • extendedAddress (String)
  • locality (String)
  • region (String)
  • postalCode (String)
  • countryCodeAlpha2 (String)
amountFloat

Required to invoke the Checkout flow. The amount of the transaction should be passed here.

currencyString

Required to invoke the Checkout flow.

localeString

Use this option to change the language, links, and terminology of the PayPal flow. This locale will be used unless the buyer has set a preferred locale for their account. If no locale is passed, a fallback locale will be used. Can be used in our Vault or Checkout flows.

Accepted values are: en_US, en_AU, da_DK, fr_FR, fr_CA, de_DE, en_GB, zh_HK, it_IT, nl_NL, no_NO, pl_PL, es_ES, sv_SE, tr_TR
Available in versions 2.26.0 and higher: pt_BR
Available in versions 2.28.0 and higher: ja_JP
Available in versions 2.31.0 and higher: id_ID, ko_KR, pt_PT, ru_RU, th_TH, zh_CN, zh_TW

headlessBoolean

Use this option if you would like to use your own custom UI to launch the PayPal flow. Defaults to false, but when set to true the PayPal button and resolution state we typically render will not be displayed. You will be required to instantiate the PayPal flow as described in the Custom UI documentation.

In addition, by setting this to true you will be required to retrieve the nonce generated from the PayPal auth flow from the onPaymentMethodReceived callback. This does not work with the Drop-in UI.

billingAgreementDescriptionString

Use this option to set the description of the pre-approved payment agreement visible to customers in their PayPal profile. Maximum 255 characters. Only available in versions 2.21.0 and higher.