Skip to main content

Card Element

Introduction​

The Card Element is a web element that integrates a secure credit card payment into your application. The Card Element provides extensive customization options, allowing you to modify the card form's appearance to match your brand's style, ensuring a professional and cohesive user experience during the payment process.

Step 1: Prepare the page​

Add the following script element to your page's html to include the Payment Elements SDK in your site:

<head>
  <script src="https://sandbox-cdn.pci.getfwd.com/sdk/forward.js"></script>

Your webpage also needs an element where it can be mounted. This is typically achieved by defining a <div> and assigning it a unique identifier. 

<div id="card-form" />

Step 2: Create a Card Element​

The Forward class can be accessed through the window object. To instantiate a Card Element, you can call the createCardElement static class helper with the following:

  • apiKey: Your public key.
  • clientSecret: The client_secret of the payment intent.
// <script>
const cardElement = await window.Forward.createCardElement({
  apiKey: 'pk_123948342832',
  clientSecret: 'pi_123948342832_secret_123948342832',
});

Step 3: Mount the Card Element​

After creating an instance of the Card Element, you can add it to the page by using the mount method.

Provide the element selector where you want the form to be placed as well as the following callbacks as arguments to the mount method:

  • onChange: (optional) This callback is invoked whenever the form contents change.
  • onReady: This callback is invoked when the user has entered a fully ready card with no errors. It receives a tokenize function that your application can call to tokenize the card.
  • onSuccess: This callback is invoked when the card is successfully tokenized. It receives a token representing a PaymentMethod id, which can be utilized to process payments on your backend.
  • onError: This callback is invoked when an error occurs during the tokenization process. It receives an error object that contains information about the error.
info

Your onSuccess callback MUST return a Promise that sends the token to your server to process the payment. If the payment is successful, the Promise should be resolved. If the payment fails, the Promise should be rejected with an error message.

The mount method returns a function that you can use to remove the Card Element from the page.

// <script>
const unmountCardElement = cardElement.mount('#card-form', {
  onChange: (event) => {
    if (!event.ready) {
      console.log('Credit card input is incomplete');
      // Disable submit/pay button
    }
    console.log(event);
  },
  onReady: (tokenize) => {
    console.log('Credit card form is ready');
    // Enable submit/pay button and call `tokenize` on click
    tokenize();
  },
  onSuccess: async ({ token }) => {
    console.log(token);
    // Send token to your server to process payment
    // Resolve promise or throw error
  },
  onError: (error) => {
    console.log(error);
  },
});

// Remove the Card Element from the page
unmountCardElement();

onChange Event​

onChange messages contain information about the correctness of the form fields or any encountered errors. The event object follows the structure of the PaymentChangedEvent type:

export type PaymentChangedEvent = {
  ready: boolean;
  empty?: boolean;
  errors?: string[];
  payment_method_type: 'card';
  card: {
    last_four_digits?: string;
    first_six_digits?: string;
    brand?: string;
    exp_month?: string;
    exp_year?: string;
    wallet?: 'apple_pay' | 'google_pay';
  };
  billing_details?: {
    address: {
      country: string;
      postal_code: string;
    };
  };
};

Appearance​

The Payment Element can be customized to match your brand's style. You can adjust the appearance of the form using additional optional attributes of the mount options object.

Style​

You can customize the appearance of the form using the style attribute of the mount options object. The style attribute provides a way to adjust various attributes, each of which corresponds to an internal CSS variable. You can use any valid CSS string as the value for these attributes to achieve the desired customization.

export type Style = {
  inputHeight?: string; // Height of input elements.
  inputPaddingLeft?: string; // Padding applied to input elements.
  inputBackgroundColor?: string; // Background color of input elements.
  borderWidth?: string; // Input border.
  borderColor?: string; // Default border color.
  borderRadius?: string;
  focusBorderColor?: string; // Color of border on focus.
  focusBoxShadow?: string; // Box shadow on input element on focus.
  errorColor?: string; // Border and text on error.
  hoverBorderColor?: string; // Border color on hover.
  textColor?: string; // Default text color applied to input and labels elements.
  fontFamily?: string; // Font family used for label elements, input elements and error messages.
  fontSize?: string; // Font size applied to input elements.
  fontStyle?: string; // Font style applied to label elements, input elements and error messages.
  fontVariant?: string; // Font variant applied to label elements, input elements and error messages.
  fontWeight?: string; // Font weight applied to text of input elements.
  labelFontWeight?: string; // Font weight of the input element label.
  labelFontSize?: string; // Font size of the input element label.
  lineHeight?: string; // Line height applied to input element text.
  letterSpacing?: string; // Letter spacing applied to all text in the iframe.
  placeholderColor?: string; // Placeholder color of input elements.
  backgroundColor?: string; // Background color of iframe container.
};

Labels​

By default, the card form includes labels for each of the input fields. However, if you prefer not to have any labels on your form, you can disable them by setting the showLabels option to false.

Example of custom style and no labels​

cardElement.mount('#card-form', {
  onReady: (tokenize) => { ... },
  onSuccess: async ({ token }) => { ... },
  onError: (error) => { ... },
  style: {
    textColor: 'red',
    borderWidth: '2',
    borderColor: 'gray',
    backgroundColor: 'green',
    inputBackgroundColor: 'white',
  },
  showLabels: false,
});