JavaScript v2

Hosted Fields

Events

You can subscribe to events using the onFieldEvent callback. This allows you to hook into focus, blur, and fieldStateChange.

JavaScript

// ...
hostedFields: {
  onFieldEvent: function (event) {
    if (event.type === 'focus') {
      // Handle focus
    } else if (event.type === 'blur') {
      // Handle blur
    } else if (event.type === 'fieldStateChange') {
      // Handle a change in validation or card type
      console.log(event.isValid); // true|false
      if (event.card) {
        console.log(event.card.type);
        // visa|master-card|american-express|diners-club|discover|jcb|unionpay|maestro
      }
    }
  }
}
// ...

The event object will return the following:

Key Type Description

type

String

`focus`	Fired when the input becomes focused
`blur`	Fired when the input loses focus
`fieldStateChange`	When any 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

`container`	Reference to the container DOM element on your page associated with the current event.
`fieldKey`	A `String` mapping to the currently associated field: `"number"` `"cvv"` `"expirationDate"` `"expirationMonth"` `"expirationYear"` `"postalCode"`

card Object The determined card type. Learn more about card type.

Card type

With each fieldStateChange event, we will return a Card Type to describe the current user input. If not enough information is available, or if there is invalid data, this value will be null.

Key Type Description

type String The code-friendly representation of the card type: visadiscovermaster-cardamerican-express, etc.

niceType String The pretty printed card type: VisaDiscoverMastercardAmerican 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`.
Key	Type	Value
`name`	`String`	`"CVV"` `"CID"` `"CVC"`
`size`	`Integer`	The expected length of the security code. Typically, this is 3 or 4

lengths Array 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)

Internally, Hosted Fields uses credit-card-type, an open-source detection library to determine card type. Visit the repo to view more detailed documentation.

Internal styling properties

These are the CSS properties that we support inside of our iframes. 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.

colorfontfont-familyfont-sizefont-size-adjustfont-stretchfont-stylefont-variantfont-variant-alternatesfont-variant-capsfont-variant-east-asianfont-variant-ligaturesfont-variant-numericfont-weightline-heightoutlineopacitytext-shadowtransition-moz-osx-font-smoothing-moz-transition-webkit-font-smoothing-webkit-transition

The following properties are supported in versions 2.18.0 and above:

-moz-tap-highlight-color-webkit-tap-highlight-color

Options

Top-level options

Inside the hostedFields configuration, the full list of options you can specify are:

Key	Type	Required	Description	Reference
`styles`	`Object`	no	A CSS-like object representing styles.	Styling
`onFieldEvent`	`function`	no	Called when events happen in any of your fields. It's passed one object called `event`.	Events
`number`	`Object`	yes	Field options for credit card number.	Field-level options
`expirationDate`	`Object`	yes	Field options for expiration month and year in `MM/YYYY` format. You may optionally split month and year into two separate fields (`expirationMonth` and `expirationYear`) if it works better with your layout.	Field-level options
`cvv`	`Object`	no	Field options for 3 or 4 digit CVV or CID.	AVS & CVV rules
`postalCode`	`Object`	no	Field options for postal code or region code.	AVS & CVV rules

* Only required when creating, saving, or using card information that is not stored in the Vault yet. When verifying cards already in the Vault, you can collect just the `cvv`.

Field-level options

Inside number, expirationDate, expirationMonth, expirationYear, cvv, and postalCode, you can specify:

Key	Type	Required	Description
`selector`	`String`	yes	String used to query the DOM for your container. Examples include: - `"#card-container"` - `".card-container"` - `"[data-name='card-container']"`
`placeholder`	`String`	no	Will be used as the `placeholder=""`.