Skip to main content

Bank Element

Introduction​

The Bank Element integrates secure bank payment functionality into your application. It provides two ways to collect bank account information: traditional manual entry with form fields, or secure bank account linking through a third-party widget that allows users to connect their accounts directly. The element also offers customization options to match your brand's style.

Note: Manual linking isn’t available by default. If you’d like to use it, please reach out to your account manager.

Step 1: Prepare the page​

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

Sandbox:

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

Production:

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

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="bank-form" />

Step 2: Create a Bank Element​

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

The Bank Element automatically fetches the payment intent or payment method intent (depending on the client secret type) and uses it to configure the element.

// <script>
const bankElement = await window.Forward.createBankElement({
  apiKey: 'test_pkey_123948342832', // Use 'live_pkey_' for production
  clientSecret: 'pi_123948342832_secret_123948342832',
});

Step 3: Mount the Bank Element​

After creating an instance of the Bank 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:

  • onSuccess: This callback is invoked when the bank account 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 should store the token in local state, then forward it to your server to either process the payment immediately or save it for future use as a payment method on file.

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

// <script>
const unmountBankElement = bankElement.mount('#bank-form', {
  onSuccess: ({ token: string }) => {
    console.log(token);
    // Send token to your server to process payment
  },
  onError: (error: string) => {
    console.log(error);
  },
});

// Remove the Bank Element from the page
unmountBankElement();

Bank Payment Methods​

The Bank Element supports multiple ways to collect bank account information:

1. Manual Bank Entry​

Traditional manual bank account entry with fields for:

  • Account holder name
  • Account holder type (business/individual)
  • Account type (checking/savings)
  • Account number
  • Routing number

2. Bank Account Linking​

Secure bank account connection through a bank-link widget that allows users to:

  • Connect their bank account directly
  • Select from their available accounts
  • Complete verification through a secure, streamlined flow

This method provides a more convenient experience for users while maintaining the highest security standards.

Appearance​

The Bank 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.
};

Example of custom style and field configuration​

bankElement.mount('#bank-form', {
  onSuccess: async ({ token }) => { ... },
  onError: (error) => { ... },
  style: {
    textColor: 'red',
    borderWidth: '2',
    borderColor: 'gray',
    backgroundColor: 'green',
    inputBackgroundColor: 'white',
  }
});

Error Handling​

The Bank Element provides error handling for various scenarios:

  • Network errors: When the payment method intent cannot be fetched
  • Validation errors: When bank account information is invalid
  • Bank linking errors: When bank account discovery or connection fails
  • Tokenization errors: When the bank account cannot be tokenized

Errors are returned as strings and passed to the onError callback with descriptive messages.