JavaScript v2

PayPal

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
`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 the Checkout flow.
`intent`	String Applies to Checkout flows (`singleUse: true`). Only available in versions 2.25.0 and higher. `authorize` (default) - Submits the transaction for authorization but not settlement. To capture funds, you must pass the `options-submit_for_settlement` option or make a separate `Transaction: Submit For Settlement` call. `sale` - Payment will be immediately submitted for settlement upon creating a transaction. The `options-submit_for_settlement` parameter will be ignored and always set to {true}.
`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 the Checkout flow). 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 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.
`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 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 the Checkout flow. The amount of the transaction should be passed here.
`currency`	String Required to invoke the Checkout flow.
`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 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 pre-approved payment agreement visible to customers in their PayPal profile. Maximum 255 characters. Only available in versions 2.21.0 and higher.