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. |
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. |
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. |
Examples
hostedFieldsInstance.clear('number', function (clearErr) {
if (clearErr) {
console.error(clearErr);
}
});
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.
Example
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. |
Example
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. |
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 |
|
callback |
callback |
<optional> |
Callback executed on completion, containing an error if one occurred. No data is returned if the placeholder updated successfully. |
Examples
hostedFieldsInstance.setPlaceholder('number', '4111 1111 1111 1111', function (placeholderErr) {
if (placeholderErr) {
console.error(placeholderErr);
}
});
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. |
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
|
||||||||||
callback |
callback | The second argument, |
Examples
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);
}
});
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:
|
|||||||||
niceType |
string | The pretty-printed card type. It will be one of the following strings:
|
|||||||||
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 Properties
|
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 |
isValid |
boolean | Whether or not the value of the associated input is fully qualified for submission. |
stateObject :object
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:
|
||||||||||||||||||||||||||||
fields |
object |
Properties
|
tokenizePayload :object
Properties:
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
nonce |
string | The payment method nonce. |
|||||||||
details |
object | Additional account details. Properties
|
|||||||||
description |
string | A human-readable description. |
|||||||||
type |
string | The payment method type, always |
Events
blur :HostedFields~stateObject
This event is emitted when a field loses focus.
Example
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.
Example
hostedFields.create({ ... }, function (createErr, hostedFieldsInstance) {
hostedFieldsInstance.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.
Example
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.
Example
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.
Example
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.
Example
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
.
Example
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');
}
});
});