HostedFields

HostedFields

This class represents a Hosted Fields component produced by braintree-web/hosted-fields.create. Instances of this class have methods for interacting with the input fields within Hosted Fields' iframes.

Constructor

new HostedFields(options)

Do not use this constructor directly. Use braintree-web.hosted-fields.create instead.

Parameters:
Name Type Description
options object

Hosted Fields create options
Source:

Methods

on(event, handler) → {void}

Subscribes a handler function to a named event, such as fieldEvent

Parameters:
Name Type Description
event string

The name of the event to subscribe to
handler function

A callback to handle the event
Source:
Example

Listening to a fieldEvent

var hostedFields = require('braintree-web/hosted-fields');

hostedFields.create({ ... }, function (err, instance) {
  instance.on('fieldEvent', function (event) {
    if (event.card != null) {
      console.log(event.card.type);
    } else {
      console.log('Type of card not yet known');
    }
  });
});

setPlaceholder(field, placeholder, callbackopt) → {void}

Sets the placeholder of a field.

Parameters:
Name Type Attributes Description
field string

The field whose placeholder you wish to change. Must be a valid fieldOption.
placeholder string

Will be used as the placeholder attribute of the input.
callback errback <optional>

Callback executed on completion, containing an error if one occurred. No data is returned if the placeholder updated successfully.
Source:
Examples
hostedFieldsInstance.setPlaceholder('number', '4111 1111 1111 1111', function (err) {
  if (err) {
    console.error(err);
  }
});

Update CVV field on card type change

var cvvPlaceholder = 'CVV'; // Create a default value

hostedFieldsInstance.on('fieldEvent', function (event) {
  if (event.target.fieldKey !== 'number') { return; } // Ignore all non-number field events

  // Update the placeholder value if the card code name has changed
  if (event.card && event.card.code.name !== cvvPlaceholder) {
    cvvPlaceholder = event.card.code.name;
    hostedFields.setPlaceholder('cvv', cvvPlaceholder, function (err) {
      if (err) {
        console.error(err);
      }
    });
  }
});

teardown(callbackopt) → {void}

Cleanly tear down anything set up by create

Parameters:
Name Type Attributes Description
callback errback <optional>

Callback executed on completion, containing an error if one occurred. No data is returned if teardown completes successfully.
Source:
Example
hostedFieldsInstance.teardown(function (err) {
  if (err) {
    console.error('Could not tear down Hosted Fields!');
  } else {
    console.info('Hosted Fields has been torn down!');
  }
});

tokenize(callback) → {void}

Attempts to tokenize fields, returning a nonce payload

Parameters:
Name Type Description
callback errback

The second argument, data, is a tokenizePayload
Source:
Example
hostedFieldsInstance.tokenize(function (err, payload) {
  if (err) {
    console.error(err);
  } else {
    console.log('Got nonce:', payload.nonce);
  }
});

Type Definitions

tokenizePayload :object

Properties:
Name Type Description
nonce string

The payment method nonce
details object

Additional account details

Properties
Name Type Description
cardType string

Type of card, ex: Visa, MasterCard
lastTwo string

Last two digits of card number
description string

A human-readable description
Source:

Events

fieldEvent :object

This event is emitted when activity within one or more inputs has resulted in a change of state, such as a field attaining focus, an input becoming empty, or the user entering enough information for us to guess the type of card.

Properties:
Name Type Attributes Description
type string
ValueMeaning
focusThe input has gained focus
blur The input has lost focus
fieldStateChange Some state has changed within an input including: validation, focus, card type detection, etc
isEmpty boolean

Whether or not the user has entered a value in the input
isFocused boolean

Whether or not the input is currently focused
isPotentiallyValid boolean

A determination based on the future validity of the input value. This is helpful when a user is entering a card number and types "41". While that value is not valid for submission, it is still possible for it to become a fully qualified entry. However, if the user enters "4x" it is clear that the card number can never become valid and isPotentiallyValid will return false.
isValid boolean

Whether or not the value of the associated input is fully qualified for submission
target object
Properties
Name Type Description
container object

Reference to the container DOM element on your page associated with the current event.
fieldKey string

The name of the currently associated field. Examples:
"number"
"cvv"
"expirationDate"
"expirationMonth"
"expirationYear"
"postalCode"
card object <nullable>

If not enough information is available, or if there is invalid data, this value will be null. Internally, Hosted Fields uses credit-card-type, an open-source detection library to determine card type.

Properties
Name Type Description
type string

The code-friendly representation of the card type: visa discover master-card american-express etc.
niceType string

The pretty-printed card type: Visa Discover MasterCard American Express etc.
code object

This object contains data relevant to the security code requirements of the card brand. For example, on a Visa card there will be a cvv of 3 digits, whereas an American Express card requires a 4-digit cid.

Properties
Name Type Description
name string

"CVV" "CID" "CVC"
size number

The expected length of the security code. Typically, this is 3 or 4
lengths Array.<number>

An array of integers of expected lengths of the card number excluding spaces, dashes, etc. (Maestro and UnionPay are card types with several possible lengths)
Source:
Example

Listening to a fieldEvent

var hostedFields = require('braintree-web/hosted-fields');

hostedFields.create({ ... }, function (err, instance) {
  instance.on('fieldEvent', function (event) {
    console.log('fieldEvent', event.type', triggered on "', event.target.fieldKey, '" field');

    if (event.card != null) {
      console.log(event.card.type);
    } else {
      console.log('Type of card not yet known');
    }
  });
});