Braintree Web Client Reference v3.112.1

• Overview
  • Module Hierarchy
  • Callbacks
  • Promises
• Browser Support
  • Desktop
  • Mobile
  • Webviews
• Teardown
• Content Security Policy

Overview

The Braintree JavaScript SDK is split up into several modules. Each module is also represented by a class encapsulating the actions that module can perform. In general, each SDK feature is represented by its own standalone module. You can include as many or as few of these modules in your page depending on the Braintree features you will be using.

Each module exports a create function which is responsible for returning an instance of that module's class. For instance, the braintree-web/paypal module's create method will return an instance of the PayPal class.

Module hierarchy

Many modules of this SDK require an instance of our Client for communicating to our servers. In these cases, a single Client instance can be used for the creation of several other module instances.

braintree.client.create(...) --------> Client ─┐
                         ┌─────────────────────┤
braintree.paypal.create(...) --------> PayPal  │
                               ┌───────────────┘
braintree.hostedFields.create(...) --> HostedFields

Callbacks

This SDK uses the Node.js callback style, with callbacks passed as the last argument to a function. Callbacks are expected to receive possible errors as the first parameter, and any returned data as the second:

braintree.client.create({...}, callback);

function callback(err, clientInstance) { ... }

Promises

In addition to callbacks, all asynchronous methods will return a Promise if no callback is provided:

braintree.client
  .create({
    authorization: CLIENT_AUTHORIZATION,
  })
  .then(function (client) {
    // Create other components
  });

Browser support

The Braintree JS SDK provides support for numerous browsers and devices. There are, however, caveats with certain integrations and browser combinations.

While braintree-web will work in browsers other than the ones below, these represent the platforms against which we actively test. If you have problems with a specific browser or device, contact our Support team.

Desktop

• Chrome latest
• Firefox latest
• Microsoft Edge latest
• Safari 8+

Mobile

iOS

• Safari 8+ (9+ for 3D Secure)
• Chrome 48+ (iOS 9+)

Android

• Native browser 4.4+
• Chrome
• Firefox

Webviews and hybrid environments

If you are using PayPal in a mobile webview, we recommend using PopupBridge for iOS or Android to open the PayPal authentication flow in a mobile browser for improved security.

Additionally, braintree-web is neither tested nor developed for hybrid runtimes such as Cordova, PhoneGap, Ionic, React Native, and Electron. While some success may be had in such environments, our SDK is optimized for the browser and its security policies and may not function correctly outside of them.

Teardown

In certain scenarios you may need to remove your braintree-web integration. This is common in single page applications, modal flows, and other situations where state management is a key factor. Any module returned from a braintree.component.create call that can be torn down will include a teardown function.

Invoking teardown will clean up any DOM nodes, event handlers, popups and/or iframes that have been created by the integration. Additionally, teardown accepts a callback which you can use to know when it is safe to proceed.

hostedFieldsInstance.teardown(function (err) {
  if (err) {
    console.error("Could not tear down Hosted Fields!");
  } else {
    console.log("Hosted Fields has been torn down!");
  }
});

If you happen to call this method while the instance's teardown is in progress, you'll receive an error. Once completed, calling any methods on the instance will throw an error.

Using braintree-web with a Content Security Policy (CSP)

Content Security Policy is a feature of web browsers that mitigates cross-site scripting and other attacks. By limiting the origins of resources that may be loaded on your page, you can maintain tighter control over any potentially malicious code. We recommend considering the implementation of a CSP when available.

Basic Directives

PayPal Specific Directives

If using the PayPal Checkout component, include these additional directives:

Google Pay Specific Directives

If using the Google Pay component, include these additional directives:

If Google adds redirects or changes URLs related to the Google Pay component, the domains or URLs in these directives may change.

3D Secure Specific Directives

If using the 3D Secure component, include these additional directives:

3D Secure 2 utilizes an iframe implementation that requires the use of the issuing bank's full ACS URL. In contrast to 3D Secure 1, the 3D Secure 2 core framework does not allow masked URLs or redirects. Given that the list of possible ACS URLs changes regularly and varies between issuers and ACS providers, there is not a strict CSP configuration available for 3D Secure 2.

Additionally, 3D Secure 2 includes a data collection flow called "3DS Method" or "Method URL Collection", which also utilizes the ACS URL directly. This process increases authentication success significantly and is considered mandatory by Visa. Blocking this process through a CSP can potentially result in authentication failures and increased friction within the checkout experience.

If maintaining a CSP in an integration that uses 3D Secure, merchants can consider setting frame-src * to whitelist all potential ACS URLs that could be utilized during the 3D Secure authentication process.

Data Collector Specific Directives

If using Kount with the Data Collector component, adhere to the Kount CSP guide.

For Braintree Fraud Protection, use these directives:

Executing In-Line Scripts

Allowing execution of any inline script(s) may lead to security vulnerabilities. To restrict the execution of inline scripts to known code, include a hash-source of the inline script(s) in the script-src directive or generate an one-time use nonce-source to allow specific <script> blocks to execute.

The generation and appropriate use of these hash-source or one-time nonce-source values are specific to your HTML files and/or server setup. See documentation on "content security policy" and "script-src" directive.

Example of hash of inline script(s):

<html><head><meta http-equiv="Content-Security-Policy" content="
    Content-Security-Policy: script-src 'unsafe-inline' 'sha256-zVu1jtS1MTItvxLN0tAAAAOAOlDFjjz/oAIlo5KIjMs='
"/><head>
<script>console.log("execution of inline-script")</script>
</html>

ℹ Try generating a hash of the contents of the <script> tag here.

⚠️ Note that any change to the <script> blocks including empty-space changes will change the hash. For example:

<script>
  console.log("execution of inline-script");
</script>

Adding empty-space around the content of the <script> tags changes the matching hash. As a result, attempts to load the HTML would show the following error (visible in the developer console):

Refused to execute inline script because it violates the following Content Security Policy directive: "script-src 'self' 'sha256-zVu1jtS1MTItvxLN0tAAAAOAOlDFjjz/oAIlo5KIjMs=' js.braintreegateway.com assets.braintreegateway.com pay.google.com". Either the 'unsafe-inline' keyword, a hash ('sha256-y5bhUNykMSWsqlMH7ObmFlUgQFkbMBMmFmeQ3H9wltI='), or a nonce ('nonce-...') is required to enable inline execution.

ℹ️ In the example above, the correct hash, sha256-y5bhUNykMSWsqlMH7ObmFlUgQFkbMBMmFmeQ3H9wltI=, appears in the last sentence of the error message.

Example of nonce-source

<html><head>
  <meta http-equiv="Content-Security-Policy" content="
    Content-Security-Policy: script-src 'unsafe-inline' 'nonce-123a456b789c000d='
"/>
<head>
<script nonce="123a456b789c000d=">console.log("execution of inline-script");</script>
<script nonce="123a456b789c000d=">var sum = 1 + 2;</script>
</html>

ℹ️️ nonce-source should be one-time use; that is, it changes for each request.

ℹ️️ nonce-source should be a randomly generated, non-guessable,cryptographically strong value; the standard of whats cryptographical strong continue to evolve, but is currently at least 128 bits.

ℹ️️ It is recommended that a nonce-source be used with HTML templating engine.