braintree-web/hosted-fields

Members

(static) VERSION :string

The current version of the SDK, i.e. 3.87.0.

Source:

Methods

(static) create(options, callbackopt) → {void}

Parameters:
Name Type Attributes Description
options object

Creation options:

Properties
Name Type Attributes Default Description
client Client <optional>

A Client instance.
authorization string <optional>

A tokenizationKey or clientToken. Can be used in place of options.client.
fields fieldOptions

A set of options for each field.
styles styleOptions <optional>

Styles applied to each field.
preventAutofill boolean <optional>
 false

When true, browsers will not try to prompt the customer to autofill their credit card information.
callback callback <optional>

The second argument, data, is the HostedFields instance. If no callback is provided, create returns a promise that resolves with the HostedFields instance.
Source:
Examples
braintree.hostedFields.create({
  client: clientInstance,
  styles: {
    'input': {
      'font-size': '16pt',
      'color': '#3A3A3A'
    },
    '.number': {
      'font-family': 'monospace'
    },
    '.valid': {
      'color': 'green'
    }
  },
  fields: {
    number: {
      container: '#card-number'
    },
    cvv: {
      container: '#cvv',
      placeholder: '•••'
    },
    expirationDate: {
      container: '#expiration-date'
    }
  }
}, callback);

With cardholder name 

braintree.hostedFields.create({
  client: clientInstance,
  fields: {
    number: {
      container: '#card-number'
    },
    cardholderName: {
      container: '#cardholder-name'
    },
    cvv: {
      container: '#cvv',
    },
    expirationDate: {
      container: '#expiration-date'
    }
  }
}, callback);

Applying styles with a class name 

// in document head
<style>
  .braintree-input-class {
    color: black;
  }
  .braintree-valid-class {
    color: green;
  }
  .braintree-invalid-class {
    color: red;
  }
</style>
// in a script tag
braintree.hostedFields.create({
  client: clientInstance,
  styles: {
    'input': 'braintree-input-class',
    '.invalid': 'braintree-invalid-class',
    '.valid': {
      // you can also use the object syntax alongside
      // the class name syntax
      color: green;
    }
  },
  fields: {
    number: {
      container: '#card-number'
    },
    // etc...
  }
}, callback);

Right to Left Language Support 

braintree.hostedFields.create({
  client: clientInstance,
  styles: {
    'input': {
      // other styles
      direction: 'rtl'
    },
  },
  fields: {
    number: {
      container: '#card-number',
      // Credit card formatting is not currently supported
      // with RTL languages, so we need to turn it off for the number input
      formatInput: false
    },
    cvv: {
      container: '#cvv',
      placeholder: '•••'
    },
    expirationDate: {
      container: '#expiration-date',
      type: 'month'
    }
  }
}, callback);

Setting up Hosted Fields to tokenize CVV only 

braintree.hostedFields.create({
  client: clientInstance,
  fields: {
    // Only add the `cvv` option.
    cvv: {
      container: '#cvv',
      placeholder: '•••'
    }
  }
}, callback);

Creating an expiration date update form with prefilled data 

var storedCreditCardInformation = {
  // get this info from your server
  // with a payment method lookup
  month: '09',
  year: '2017'
};

braintree.hostedFields.create({
  client: clientInstance,
  fields: {
    expirationMonth: {
      container: '#expiration-month',
      prefill: storedCreditCardInformation.month
    },
    expirationYear: {
      container: '#expiration-year',
      prefill: storedCreditCardInformation.year
    }
  }
}, callback);

Validate the card form for supported card types 

braintree.hostedFields.create({
  client: clientInstance,
  fields: {
    number: {
      container: '#card-number',
      supportedCardBrands: {
        visa: false, // prevents Visas from showing up as valid even when the Braintree control panel is configured to allow them
        'diners-club': true // allow Diners Club cards to be valid (processed as Discover cards on the Braintree backend)
      }
    },
    cvv: {
      container: '#cvv',
      placeholder: '•••'
    },
    expirationDate: {
      container: '#expiration-date',
      type: 'month'
    }
  },
}, callback);

(static) supportsInputFormatting() → {Boolean}

Returns false if input formatting will be automatically disabled due to browser incompatibility. Otherwise, returns true. For a list of unsupported browsers, go here.

Source:
Example

Conditionally choosing split expiration date inputs if formatting is unavailable 

var canFormat = braintree.hostedFields.supportsInputFormatting();
var fields = {
  number: {
    container: '#card-number'
  },
  cvv: {
    container: '#cvv'
  }
};

if (canFormat) {
  fields.expirationDate = {
    selection: '#expiration-date'
  };
  functionToCreateAndInsertExpirationDateDivToForm();
} else {
  fields.expirationMonth = {
    selection: '#expiration-month'
  };
  fields.expirationYear = {
    selection: '#expiration-year'
  };
  functionToCreateAndInsertExpirationMonthAndYearDivsToForm();
}

braintree.hostedFields.create({
  client: clientInstance,
  styles: {
    // Styles
  },
  fields: fields
}, callback);

Type Definitions

field :object

Fields used in fields options

Properties:
Name Type Attributes Default Description
selector string

Deprecated: Now an alias for options.container.
container string | HTMLElement

A DOM node or CSS selector to find the container where the hosted field will be inserted.
placeholder string <optional>

Will be used as the placeholder attribute of the input. If placeholder is not natively supported by the browser, it will be polyfilled.
type string <optional>

Will be used as the type attribute of the input. To mask cvv input, for instance, type: "password" can be used.
iframeTitle string <optional>

The title used for the iframe containing the credit card input. By default, this will be Secure Credit Card Frame - <the name of the specific field>.
internalLabel string <optional>

Each Hosted Field iframe has a hidden label that is used by screen readers to identify the input. The internalLabel property can be used to customize the field for localization purposes. The default values are:

  • number: Credit Card Number
  • cvv: CVV
  • expirationDate: Expiration Date
  • expirationMonth: Expiration Month
  • expirationYear: Expiration Year
  • postalCode: Postal Code
  • cardholderName: Cardholder Name
formatInput boolean <optional>
 true

Enable or disable automatic formatting on this field.
maskInput object | boolean <optional>
 false

Enable or disable input masking when input is not focused. If set to true instead of an object, the defaults for the maskInput parameters will be used.

Properties
Name Type Attributes Default Description
character string <optional>
 •

The character to use when masking the input. The default character ('•') uses a unicode symbol, so the webpage must support UTF-8 characters when using the default.
showLastFour Boolean <optional>
 false

Only applicable for the credit card field. Whether or not to show the last 4 digits of the card when masking.
select object | boolean <optional>

If truthy, this field becomes a <select> dropdown list. This can only be used for expirationMonth and expirationYear fields. If you do not use a placeholder property for the field, the current month/year will be the default selected value.

Properties
Name Type Attributes Description
options Array.<string> <optional>

An array of 12 strings, one per month. This can only be used for the expirationMonth field. For example, the array can look like ['01 - January', '02 - February', ...].
maxCardLength number <optional>

This option applies only to the number field. Allows a limit to the length of the card number, even if the card brand may support numbers of a greater length. If the value passed is greater than the max length for a card brand, the smaller number of the 2 values will be used. For example, is maxCardLength is set to 16, but an American Express card is entered (which has a max card length of 15), a max card length of 15 will be used.
maxlength number <optional>

This option applies only to the CVV and postal code fields. Will be used as the maxlength attribute of the input. The primary use cases for the maxlength option are: limiting the length of the CVV input for CVV-only verifications when the card type is known and setting the length of the postal code input when cards are coming from a known region. The default maxlength for the postal code input is 10.
minlength number <optional>
 3

This option applies only to the cvv and postal code fields. Will be used as the minlength attribute of the input. For postal code fields, the default value is 3, representing the Icelandic postal code length. This option's primary use case is to increase the minlength, e.g. for US customers, the postal code minlength can be set to 5. For cvv fields, the default value is 3. The minlength attribute only applies to integrations capturing a cvv without a number field.
prefill string <optional>

A value to prefill the field with. For example, when creating an update card form, you can prefill the expiration date fields with the old expiration date data.
rejectUnsupportedCards boolean <optional>
 false

Deprecated since version 3.46.0, use supportedCardBrands instead. Only allow card types that your merchant account is able to process. Unsupported card types will invalidate the card form. e.g. if you only process Visa cards, a customer entering a American Express card would get an invalid card field. This can only be used for the number field.
supportedCardBrands object <optional>

Override card brands that are supported by the card form. Pass 'card-brand-id': true to override the default in the merchant configuration and enable a card brand. Pass 'card-brand-id': false to disable a card brand. Unsupported card types will invalidate the card form. e.g. if you only process Visa cards, a customer entering an American Express card would get an invalid card field. This can only be used for the number field. (Note: only allow card types that your merchant account is actually able to process.)

Valid card brand ids are:

  • visa
  • mastercard
  • american-express
  • diners-club
  • discover
  • jcb
  • union-pay
  • maestro
  • elo
  • mir
  • hiper
  • hipercard
Source:

fieldOptions :object

An object that has field objects for each field. Used in create.

Properties:
Name Type Attributes Description
number field <optional>

A field for card number.
expirationDate field <optional>

A field for expiration date in MM/YYYY or MM/YY format. This should not be used with the expirationMonth and expirationYear properties.
expirationMonth field <optional>

A field for expiration month in MM format. This should be used with the expirationYear property.
expirationYear field <optional>

A field for expiration year in YYYY or YY format. This should be used with the expirationMonth property.
cvv field <optional>

A field for 3 or 4 digit card verification code (like CVV or CID). If you wish to create a CVV-only payment method nonce to verify a card already stored in your Vault, omit all other fields to only collect CVV.
postalCode field <optional>

A field for postal or region code.
cardholderName field <optional>

A field for the cardholder name on the customer's credit card.
Source:

styleOptions :object

An object that represents CSS that will be applied in each hosted field. This object looks similar to CSS. Typically, these styles involve fonts (such as font-family or color).

You may also pass the name of a class on your site that contains the styles you would like to apply. The style properties will be automatically pulled off the class and applied to the Hosted Fields inputs. Note: this is recommended for input elements only. If using a select for the expiration date, unexpected styling may occur.

These are the CSS properties that Hosted Fields supports. Any other CSS should be specified on your page and outside of any Braintree configuration. Trying to set unsupported properties will fail and put a warning in the console.

Supported CSS properties are: appearance box-shadow color direction font-family font-size-adjust font-size font-stretch font-style font-variant-alternates font-variant-caps font-variant-east-asian font-variant-ligatures font-variant-numeric font-variant font-weight font letter-spacing line-height opacity outline margin margin-top margin-right margin-bottom margin-left padding padding-top padding-right padding-bottom padding-left text-align text-shadow transition -moz-appearance -moz-box-shadow -moz-osx-font-smoothing -moz-tap-highlight-color -moz-transition -webkit-appearance -webkit-box-shadow -webkit-font-smoothing -webkit-tap-highlight-color -webkit-transition

Source: