Collect card information

Rendering card fields

Start by creating elements context using moneyhash.elements, this method takes an object of type ElementsProps and returns Elements object

const elements = moneyhash.elements({
  styles: {
    color: "<text-color>" | { base: "<text-color>", error: "text-color" },
    backgroundColor: "<bg-color>",
    placeholderColor: "<placeholder-color>",
    fontSize: "<font-size>",
    fontFamily: "<font-family>",
    fontStyle: "normal" | "italic" | "oblique",
    fontWeight: "<font-weight>",
    padding: "<padding>",
    height: "<height>",
    direction: "ltr" | "rtl",
    textAlign: "left" | "center" | "right",
  },
  classes: {
    focus: "border border-blue-600",
    error: "border border-red-500",
  },
  // custom font family
  fontSourceCss: "<absolute URL pointing to a CSS file with @font-face definitions>
});

The passed styles property holds the styles that will be applied to all input fields iframes, however, it can be further customized for each field. The return of moneyhash.elements method is Elements object that will be used to create each card field.

To create each card field, use elements.create method which takes ElementProps object and returns Element object. The method is expecting you to pass the elementType which is one of the following types:

1. cardHolderName
2. cardNumber
3. cardCvv
4. cardExpiryMonth
5. cardExpiryYear

Also pass the elementOptions. The following table describes the values of elementOptions:

By creating the element of each field, you will get access to mount and on methods from the element object. The mount function will attach the element inside the container having the selector as id attribute, while on will enable you to listen to the ElementEvents of the field and fire a custom callback.

const cardHolderNameEl = elements.create({
  elementType: "cardHolderName",
  elementOptions: {
    selector: "#card-holder-name", // make sure to have an element with this selector inside the DOM
    placeholder: "Enter card holder name...",
    styles: {},
    classes: {},
  },
});

cardHolderName.on("mount", () => {
  console.log("card holder name  mounted");
  cardHolderName.focus();
});

cardHolderName.on("focus", () => {
  console.log("card holder name focus");
});

cardHolderName.on("blur", () => {
  console.log("card holder name blur");
});

cardHolderName.on("changeInput", ({ isValid, length }) => {
  console.log("card holder name is changing", { isValid, length });
});

cardHolderName.off("blur"); // unsubscribe from blur event
                   
cardHolderName.mount(); // will add the field to the DOM inside the container with card-holder-name id attribute

Collect Card Data

Collect card data to pay with or save the card for future use.

const cardData = await moneyHash.cardForm.collect();

Card Elements Events

Using element.on method, you can listen for certain input events and act accordingly.

• mount: An event will fire when the input is mounted and ready for interaction from user.
• focus: An event will fire when the input is in focus state.
• blur: An event will fire when the input is in blur state.
• error: An event that fires in runtime giving the validity state of the element while user is interacting with it. This event receives a payload containing isValid a boolean indicating state of the element and error which will have the error string if it is invalid and null otherwise.
• changeInput: An event will be firing while the input is being changed.
• cardNumberChange: A special event related to cardNumber element. This event will fire when the user changes the first 6 digits. The callback of this event will receive a payload containing first6Digits first8Digits, brand, and brandIconUrl of the card. If the card number is not recognized you will get Unknown card info. If the card number is removed after, this event will fire with the Unknown card info.
• key:Backspace An event will fire when the keyboard Backspace is pressed.
• key:Enter An event will fire when the keyboard Enter is pressed.

To unsubscribe from an event, use element.off and pass the event name. This will remove the listener you attached before.

Card Elements Methods

You can programmatically focus, blur, and clear at any time using element methods

• focus Focuses the card element.
• blur Removes keyboard focus from the card element.
• clearClears the card element value.

There is an event that fires when the validity state of the whole form changes. This event is called validityChange. To listen to this event use the Elements object created at the beginning. elements.onaccepts the event name and a callback which receives the validity state.

elements.on("validityChange", (isValid) => {
	console.log(isValid);
});

📘

MoneyHash considers card number valid based on the length only. Card number with length from 13 to 19 are considered valid.

Basic Luhn algo card number validation is applied automatically from v1.18.0 & v.2.4.0
and can be enabled/disabled by updating cardNumber validation.cardNumber element options.

Custom Classes

When each element is mounted, it will have by default some classes attached to the container of the element. The default classes are .MoneyHashElement attached to all elements, and two classes based on focus and error events which are .MoneyHashElement--focus and .MoneyHashElement--error. However, you can customize classes of focus and error events using classes property which can be passed for all elements while using moneyhash.elements or for each element while using element.create. classes is an object that contains focus | error as key and the space separated custom classes names as a string.

Localization

By default, the direction of the elements will be inherited from the set locale in MoneyHash instance. Currently, the supported locales are "en" | "ar" | "fr". However, you can override the default direction of the instance language either on the level of all elements of for a specific element by setting the direction property to either ltr or rtl.

In addition to element direction, the set locale will also affect the error messages that you receive when validating the card elements or when submitting the form.

// Full example to create cardHolderName field and mount it.

const cardHolderNameEl = elements.create({
  elementType: "cardHolderName",
  elementOptions: {
    selector: "#card-holder-name", // make sure to have an element with this selector inside the DOM
    placeholder: "Enter card holder name...",
    styles: {
      color: "red",
      backgroundColor: "black",
      placeholderColor: "#ccc",
      height: "40px",
      fontSize: "14px",
      padding: "8px",
      direction: "rtl",
    },
    classes: {
      focus: "border border-blue-600",
      error: "border border-red-500",
    },
  },
});

cardHolderName.on("mount", () => {
  console.log("card holder name  mounted");
  cardHolderName.focus();
});

cardHolderName.on("focus", () => {
  console.log("card holder name focus");
});

cardHolderName.on("blur", () => {
  console.log("card holder name blur");
});

cardHolderName.on("changeInput", ({ isValid, length }) => {
  console.log("card holder name is changing", { isValid, length });
});

cardHolderName.off("blur"); // unsubscribe from blur event
                   
cardHolderName.mount(); // will attach the field to the DOM inside the container with card-holder-name id attribute

❗️

JS SDK expects all required fields to be rendered. Otherwise you will receive an error indicating that missing field is required.

Currently all card elements are required except cardHolderName, it is optional and can be omitted. However, you have the ability to make it required based in your needs. Achieving this by passing validation.required value to elementOptions while creating the cardHolderName element.