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

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

Clear several fields

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

on(event, handler) → {void}

Subscribes a handler function to a named hostedFieldsEvent. event should be blur, focus, empty, notEmpty, cardTypeChange, or validityChange.

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 (err, instance) {
  instance.on('focus', function (event) {
    console.log(event.emittedBy, 'has been focused');
  });
});

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

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 (err) {
      if (err) {
        // Handle errors, such as invalid field name
        console.error(err);
      }
    });
  }
});

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 (err) {
  if (err) {
    console.error('Could not tear down Hosted Fields!');
  } else {
    console.info('Hosted Fields has been torn down!');
  }
});

tokenize(callback) → {void}

Tokenizes fields and returns a nonce payload.

Parameters:
Name Type Description
callback callback

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

hostedFieldsEvent :object

The event payload sent from on.

Properties:
Name Type Description
emittedBy string

The name of the field associated with this event. It will be one of the following strings:

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

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

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

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

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

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

hostedFieldsEventFieldData for the postal code field, if it is present.
cards Array.<HostedFields~hostedFieldsEventCard>

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.
Source:

hostedFieldsEventCard :object

Information about the card type, sent in hostedFieldEvent objects.

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:

hostedFieldsEventFieldData :object

Data about Hosted Fields fields, sent in hostedFieldEvent objects.

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:

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

blur :HostedFields~hostedFieldsEvent

This hostedFieldsEvent is emitted when a field loses focus.

Source:
Example

Listening to a blur event

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

cardTypeChange :HostedFields~hostedFieldsEvent

This hostedFieldsEvent 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 (err, instance) {
  instance.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~hostedFieldsEvent

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

Source:
Example

Listening to an empty event

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

focus :HostedFields~hostedFieldsEvent

This hostedFieldsEvent is emitted when a field gains focus.

Source:
Example

Listening to a focus event

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

inputSubmitRequest :HostedFields~hostedFieldsEvent

This hostedFieldsEvent 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 (err, instance) {
  instance.on('inputSubmitRequest', function () {
    // User requested submission, e.g. by pressing Enter or equivalent
    submitButton.click();
  });
});

notEmpty :HostedFields~hostedFieldsEvent

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

Source:
Example

Listening to an notEmpty event

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

validityChange :HostedFields~hostedFieldsEvent

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

Source:
Example

Listening to a validityChange event

hostedFields.create({ ... }, function (err, instance) {
  instance.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');
    }
  });
});