JavaScript v2

Hosted Fieldsanchor


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

  1. 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) {
        // 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.

A String mapping to the currently associated field:







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

Card typeanchor

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

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.

color font font-family font-size font-size-adjust font-stretch font-style font-variant font-variant-alternates font-variant-caps font-variant-east-asian font-variant-ligatures font-variant-numeric font-weight line-height outline opacity text-shadow transition -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


Top-level optionsanchor

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

stylesObjectnoA CSS-like object representing styles.Styling
onFieldEventfunctionnoCalled when events happen in any of your fields. It's passed one object called event.Events
numberObjectyesField options for credit card number.Field-level options
expirationDateObjectyesField 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
cvvObjectnoField options for 3 or 4 digit CVV or CID.AVS & CVV rules
postalCodeObjectnoField 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 optionsanchor

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="".