Options

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
container Required
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" />
displayName String
The merchant name displayed inside of the PayPal lightbox; defaults to the company name on your Braintree account.
singleUse Boolean
Defaults to false, but can be set to true to trigger Express Checkout.
intent String
Applies to Checkout flows (singleUse: true). Only available in versions 2.25.0 and higher.
onUnsupported Function
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 Express Checkout). This callback is not available in the Drop-in UI.
onCancelled Function
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.
onSuccess Deprecated
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 sucessfully 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.
onAuthorizationDismissed Function
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.
enableShippingAddress Boolean
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)
shippingAddressOverride Object
Allows you to pass a shipping address you have already collected into the PayPal payment flow. Full examples on Vault and Express 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.
enableBillingAddress Boolean
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)
amount Float
Required to invoke Express Checkout. The amount of the transaction should be passed here.
currency String
Required to invoke Express Checkout.
locale String
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 Express 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

headless Boolean
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.
billingAgreementDescription String
Use this option to set the description of the preapproved payment agreement visible to customers in their PayPal profile. Max 255 characters. Only available in versions 2.21.0 and higher.

Still Have Questions?

If you can’t find an answer, give us a call at 877.434.2894 or contact our Support team