Subscribe to credit and debit card field events

Subscribe to events

You can subscribe to advanced credit and debit card payments events using an event listener. This allows you to update the UI of your form based on the state of the fields. These events include:

Set up an event listener using the advanced credit and debit card payments on() function. You can use the event object to get information about your fields and update your UI accordingly.

Here is an example of how you can use cardTypeChange to update your CVV label and placeholder:

paypal.HostedFields.render({ /* ... */ }).then(function (hostedFieldsInstance) {
 var cvvLabel = document.querySelector('label[for="cvv"]'); // The label for your CVV field

 hostedFieldsInstance.on('cardTypeChange', function (event) {
   // This event triggers when a change in card type is detected.
   // It triggers only from the number field.
   var cvvText;

   if (event.cards.length === 1) {
     cvvText = event.cards[0].code.name;
   } else {
     cvvText = 'CVV';
   }

   cvvLabel.innerHTML = cvvText;
   hostedFieldsInstance.setAttribute({
     field: 'cvv',
     attribute: 'placeholder',
     value: cvvText
   });
 });
});

To get the state of your form without using events, use the getState function. This example uses getState to confirm that all of the provided fields are valid before form submission.

var form = document.querySelector('#my-sample-form');

paypal.HostedFields.render({ /* ... */ }).then(function (hostedFieldsInstance) {
  form.addEventListener('submit', function (event) {
    var state = hostedFieldsInstance.getState();
    var formValid = Object.keys(state.fields).every(function (key) {
      return state.fields[key].isValid;
    });

    if (formValid) {
      // Submit Hosted Fields card data
      hostedFieldsInstance.submit();
    } else {
      // Let the customer know their fields are invalid
    }
  });
});

Examples

Here are examples of how you might use the event listeners.

focus

This event triggers when a field gains focus.

paypal.HostedFields.render({ /* ... */ }).then(function (hostedFieldsInstance) {
  hostedFieldsInstance.on('focus', function (event) {
    // Your actions on focus
    console.log(event.emittedBy, 'gained focus');
  });
});

blur

This event triggers when a field loses focus.

paypal.HostedFields.render({ /* ... */ }).then(function (hostedFieldsInstance) {
  hostedFieldsInstance.on('blur', function (event) {
    // Your actions on blur
    console.log(event.emittedBy, 'lost focus');
  });
});

empty

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

paypal.HostedFields.render({ /* ... */ }).then(function (hostedFieldsInstance) {
  hostedFieldsInstance.on('empty', function (event) {
    // Your actions on empty  
    console.log(event.emittedBy, 'is now empty');
  });
});

notEmpty

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

paypal.HostedFields.render({ /* ... */ }).then(function (hostedFieldsInstance) {
  hostedFieldsInstance.on('notEmpty', function (event) {
    console.log(event.emittedBy, 'has data');
  });
});

cardTypeChange

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

paypal.HostedFields.render({ /* ... */ }).then(function (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');
    }
  });
});

validityChange

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

paypal.HostedFields.render({ /* ... */ }).then(function (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');
    }
  });
});

inputSubmitRequest

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

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

paypal.HostedFields.render({ /* ... */ }).then(function (hostedFieldsInstance) {
  hostedFieldsInstance.on('inputSubmitRequest', function () {
    // User requested submission, e.g. by pressing Enter or equivalent
    submitButton.click();
  });
});

Methods

• render()
• isEligible()
• addClass()
• clear()
• focus()
• getstate()
• on()
• removeAttribute()
• setAttribute()
• removeClass()
• setMessage()

render()

render(options) → {Promise|void}

The render() method creates an instance of advanced credit and debit card payments and renders the card fields for checkout based on the mapping and styles provided by options. Includes the following parameters:

isEligible()

isEligible() → {boolean}

The isEligible() method checks if advanced credit and debit card payments are eligible to render, based on configuration and business rules.

addClass()

addClass(field, classname, callback<sub>opt</sub>) → {Promise|void}

The addClass1() method adds a class to a field. It is useful for updating field styles when events occur elsewhere in your checkout integration. Includes the following parameters:

clear()

clear(field, callback<sub>opt</sub>) → {Promise|void}

The clear() method clears the value of a field. Includes the following parameters:

focus()

focus(field, callback<sub>opt</sub>) → {void}

The focus() method programmatically focuses a field. Includes the following parameters:

getState()

getState() → {object}

The getState() method returns an object that includes the state of all fields and possible card types.

on()

on(event, handler) → {void}

The on() method subscribes a handler function to a named event. Events include:

• blur
• focus
• empty
• notEmpty
• cardTypeChange
• validityChange

Events trigger a stateObject. Includes the following parameters:

removeAttribute()

removeAttribute(options, callback<sub>opt</sub>) → {Promise|void}

The removeAttribute() method removes a supported attribute from a field. Includes the following parameters:

setAttribute()

setAttribute(options, callback<sub>opt</sub>) → {Promise|void}

The setAttribute() method sets an attribute of a field. Supported attributes are aria-invalid, aria-required, disabled, and placeholder. Includes the following parameters:

removeClass()

removeClass(field, classname, callback<sub>opt</sub>) → {Promise|void}

The removeClass() method removes a class to a field. Useful for updating field styles when events occur elsewhere in your checkout integration. Includes the following parameters:

setMessage()

setMessage(options) → {void}

The setMessage() method sets a visually hidden message for screen readers on a field. Includes the following parameter:

Type definitions

• field
• fieldOptions
• styleOptions
• cardSecurityCode
• hostedFieldsCard
• hostedFieldsFieldData
• stateObject

field

Fields used in fieldOptions object.

fieldOptions

An object that has field objects for each field. Used in render() method.

styleOptions

An object that represents CSS that is applied in each card field. This object looks similar to CSS. Typically, these styles involve fonts such as font-family or color.

You can also pass the name of a class on your site that contains the styles you want to apply. The style properties are automatically pulled off the class and applied to the card field inputs.

Note: Recommended for input elements only. If using a select for the expiration date, unexpected styling might occur.

cardSecurityCode

Information about the security code for a card.

hostedFieldsCard

Information about the card type, sent in stateObjects.

hostedFieldsFieldData

Fields data for advanced credit and debit card payments is sent in stateObjects.

stateObject

The event payload is sent from on or getState.