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

The Hosted Fields create options.
Source:

Methods

addClass(field, classname, callbackopt) → {void}

Add a class to a field. Useful for updating field styles when events occur elsewhere in your checkout.

Parameters:
Name Type Attributes Description
field string

The field you wish to add a class to. Must be a valid fieldOption.
classname string

The class to be added.
callback callback <optional>

Callback executed on completion, containing an error if one occurred. No data is returned if the class is added successfully.
Source:
Example
hostedFieldsInstance.addClass('number', 'custom-class', function (addClassErr) {
  if (addClassErr) {
    console.error(addClassErr);
  }
});

clear(field, callbackopt) → {void}

Clear the value of a field.

Parameters:
Name Type Attributes Description
field string

The field whose placeholder you wish to clear. Must be a valid fieldOption.
callback callback <optional>

Callback executed on completion, containing an error if one occurred. No data is returned if the field cleared successfully.
Source:
Examples
hostedFieldsInstance.clear('number', function (clearErr) {
  if (clearErr) {
    console.error(clearErr);
  }
});

Clear several fields

hostedFieldsInstance.clear('number');
hostedFieldsInstance.clear('cvv');
hostedFieldsInstance.clear('expirationDate');

getState() → {object}

Returns an object that includes the state of all fields and possible card types.

Source:
Example

Check if all fields are valid

var state = hostedFields.getState();

var formValid = Object.keys(state.fields).every(function (key) {
  return state.fields[key].isValid;
});

on(event, handler) → {void}

Subscribes a handler function to a named event. event should be blur, focus, empty, notEmpty, cardTypeChange, or validityChange. Events will emit a stateObject.

Parameters:
Name Type Description
event string

The name of the event to which you are subscribing.
handler function

A callback to handle the event.
Source:
Example

Listening to a Hosted Field event, in this case 'focus'

hostedFields.create({ ... }, function (createErr, hostedFieldsInstance) {
  hostedFieldsInstance.on('focus', function (event) {
    console.log(event.emittedBy, 'has been focused');
  });
});

removeClass(field, classname, callbackopt) → {void}

Removes a class to a field. Useful for updating field styles when events occur elsewhere in your checkout.

Parameters:
Name Type Attributes Description
field string

The field you wish to remove a class from. Must be a valid fieldOption.
classname string

The class to be removed.
callback callback <optional>

Callback executed on completion, containing an error if one occurred. No data is returned if the class is removed successfully.
Source:
Example
hostedFieldsInstance.addClass('number', 'custom-class', function (addClassErr) {
  if (addClassErr) {
    console.error(addClassErr);
    return;
  }

  // some time later...
  hostedFieldsInstance.removeClass('number', 'custom-class');
});

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 callback <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 (placeholderErr) {
  if (placeholderErr) {
    console.error(placeholderErr);
  }
});

Update CVV field on card type change

hostedFieldsInstance.on('cardTypeChange', function (event) {
  // Update the placeholder value if there is only one possible card type
  if (event.cards.length === 1) {
    hostedFields.setPlaceholder('cvv', event.cards[0].code.name, function (placeholderErr) {
      if (placeholderErr) {
        // Handle errors, such as invalid field name
        console.error(placeholderErr);
      }
    });
  }
});

teardown(callbackopt) → {void}

Cleanly tear down anything set up by create

Parameters:
Name Type Attributes Description
callback callback <optional>

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

tokenize(optionsopt, callback) → {void}

Tokenizes fields and returns a nonce payload.

Parameters:
Name Type Attributes Description
options object <optional>

All tokenization options for the Hosted Fields component.

Properties
Name Type Attributes Default Description
vault boolean <optional>
 false

When true, will vault the tokenized card. Cards will only be vaulted when using a client created with a client token that includes a customer ID.
callback callback

The second argument, data, is a tokenizePayload
Source:
Examples

Tokenize a card

hostedFieldsInstance.tokenize(function (tokenizeErr, payload) {
  if (tokenizeErr) {
    switch (tokenizeErr.code) {
      case 'HOSTED_FIELDS_FIELDS_EMPTY':
        console.error('All fields are empty! Please fill out the form.');
        break;
      case 'HOSTED_FIELDS_FIELDS_INVALID':
        console.error('Some fields are invalid:', tokenizeErr.details.invalidFieldKeys);
        break;
      case 'HOSTED_FIELDS_FAILED_TOKENIZATION':
        console.error('Tokenization failed server side. Is the card valid?');
        break;
      case 'HOSTED_FIELDS_TOKENIZATION_NETWORK_ERROR':
        console.error('Network error occurred when tokenizing.');
        break;
      default:
        console.error('Something bad happened!', tokenizeErr);
    }
  } else {
    console.log('Got nonce:', payload.nonce);
  }
});

Tokenize and vault a card

hostedFieldsInstance.tokenize({
  vault: true
}, function (tokenizeErr, payload) {
  if (tokenizeErr) {
    console.error(tokenizeErr);
  } else {
    console.log('Got nonce:', payload.nonce);
  }
});

Type Definitions

hostedFieldsCard :object

Information about the card type, sent in stateObjects.

Properties:
Name Type Description
type string

The code-friendly representation of the card type. It will be one of the following strings:

  • american-express
  • diners-club
  • discover
  • jcb
  • maestro
  • master-card
  • unionpay
  • visa
niceType string

The pretty-printed card type. It will be one of the following strings:

  • American Express
  • Diners Club
  • Discover
  • JCB
  • Maestro
  • MasterCard
  • UnionPay
  • Visa
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.
Source:

hostedFieldsFieldData :object

Data about Hosted Fields fields, sent in stateObjects.

Properties:
Name Type Description
container HTMLElement

Reference to the container DOM element on your page associated with the current event.
isFocused boolean

Whether or not the input is currently focused.
isEmpty boolean

Whether or not the user has entered a value in the input.
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.
Source:

stateObject :object

The event payload sent from on or getState.

Properties:
Name Type Description
cards Array.<HostedFields~hostedFieldsCard>

This will return an array of potential cards. If the card type has been determined, the array will contain only one card. Internally, Hosted Fields uses credit-card-type, an open-source card detection library.
emittedBy string

The name of the field associated with an event. This will not be included if returned by getState. It will be one of the following strings:

  • "number"
  • "cvv"
  • "expirationDate"
  • "expirationMonth"
  • "expirationYear"
  • "postalCode"
fields object
Properties
Name Type Attributes Description
number HostedFields~hostedFieldsFieldData <nullable>

hostedFieldsFieldData for the number field, if it is present.
cvv HostedFields~hostedFieldsFieldData <nullable>

hostedFieldsFieldData for the CVV field, if it is present.
expirationDate HostedFields~hostedFieldsFieldData <nullable>

hostedFieldsFieldData for the expiration date field, if it is present.
expirationMonth HostedFields~hostedFieldsFieldData <nullable>

hostedFieldsFieldData for the expiration month field, if it is present.
expirationYear HostedFields~hostedFieldsFieldData <nullable>

hostedFieldsFieldData for the expiration year field, if it is present.
postalCode HostedFields~hostedFieldsFieldData <nullable>

hostedFieldsFieldData for the postal code field, if it is present.
Source:

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.
type string

The payment method type, always CreditCard.
Source:

Events

blur :HostedFields~stateObject

This event is emitted when a field loses focus.

Source:
Example

Listening to a blur event

hostedFields.create({ ... }, function (createErr, hostedFieldsInstance) {
  hostedFieldsInstance.on('blur', function (event) {
    console.log(event.emittedBy, 'lost focus');
  });
});

cardTypeChange :HostedFields~stateObject

This event is emitted when activity within the number field has changed such that the possible card type has changed.

Source:
Example

Listening to a cardTypeChange event

hostedFields.create({ ... }, function (createErr, hostedFieldsInstance) {
  hosteFieldsInstance.on('cardTypeChange', function (event) {
    if (event.cards.length === 1) {
      console.log(event.cards[0].type);
    } else {
      console.log('Type of card not yet known');
    }
  });
});

empty :HostedFields~stateObject

This event is emitted when a field transitions from having data to being empty.

Source:
Example

Listening to an empty event

hostedFields.create({ ... }, function (createErr, hostedFieldsInstance) {
  hostedFieldsInstance.on('empty', function (event) {
    console.log(event.emittedBy, 'is now empty');
  });
});

focus :HostedFields~stateObject

This event is emitted when a field gains focus.

Source:
Example

Listening to a focus event

hostedFields.create({ ... }, function (createErr, hostedFieldsInstance) {
  hostedFieldsInstance.on('focus', function (event) {
    console.log(event.emittedBy, 'gained focus');
  });
});

inputSubmitRequest :HostedFields~stateObject

This event is emitted when the user requests submission of an input field, such as by pressing the Enter or Return key on their keyboard, or mobile equivalent.

Source:
Example

Clicking a submit button upon hitting Enter (or equivalent) within a Hosted Field

var hostedFields = require('braintree-web/hosted-fields');
var submitButton = document.querySelector('input[type="submit"]');

hostedFields.create({ ... }, function (createErr, hostedFieldsInstance) {
  hostedFieldsInstance.on('inputSubmitRequest', function () {
    // User requested submission, e.g. by pressing Enter or equivalent
    submitButton.click();
  });
});

notEmpty :HostedFields~stateObject

This event is emitted when a field transitions from being empty to having data.

Source:
Example

Listening to an notEmpty event

hostedFields.create({ ... }, function (createErr, hostedFieldsInstance) {
  hostedFieldsInstance.on('notEmpty', function (event) {
    console.log(event.emittedBy, 'is now not empty');
  });
});

validityChange :HostedFields~stateObject

This event is emitted when the validity of a field has changed. Validity is represented in the stateObject as two booleans: isValid and isPotentiallyValid.

Source:
Example

Listening to a validityChange event

hostedFields.create({ ... }, function (createErr, hostedFieldsInstance) {
  hostedFieldsInstance.on('validityChange', function (event) {
    var field = event.fields[event.emittedBy];

    if (field.isValid) {
      console.log(event.emittedBy, 'is fully valid');
    } else if (field.isPotentiallyValid) {
      console.log(event.emittedBy, 'is potentially valid');
    } else {
      console.log(event.emittedBy, 'is not valid');
    }
  });
});