Get up and running with Forage’s JavaScript SDK to accept HSA/FSA and EBT payments online. This guide walks you through the installation, setup, styling, and execution of key payment operations.

In this guide, you’ll learn how to:

Step 1: Initialize a ForagePaymentSheetElement
Step 2: Style a ForagePaymentSheetElement
Step 3: Set up text input validation
Step 4: Tokenize an HSAFSA payment method

Prerequisites

Before we get started, make sure you have the following ready to go:

A Forage account
(Contact us if you don’t have one yet.)
forage-js-sdk package version 1.3.0 or later

For more information, see:

Payments API reference docs

Step 1: Initialize a ForagePaymentSheetElement

A Forage Payment Sheet is a secure, client-side entity that accepts and submits customer input for an HSA/FSA transaction.

The JS SDK includes a ForagePaymentSheetElement for collecting all of the required HSA/FSA card data, pictured below.

Example HSA/FSA payment form.

Create a parent container for the Forage Element, as in the following example:

<div id="card-tokenization-form-container" style="width: 500px; height: 500px;"></div>

After initializing Forage JS, create and add the ForagePaymentSheetElement component to your front-end checkout flow to collect a customer’s HSA/FSA Card number (Create a ForagePaymentSheetElement).

const paymentSheetElement = forage.create('payment_sheet', {
        paymentSheet: {
          paymentType: 'HSAFSA',
	   // provide the label text and/or placeholder text for each field
          fields: {
            cardHolderName: {
              labelText: 'Full name',
              placeholderText: 'John Doe',
            },
            cardNumber: {
              labelText: 'Card number',
              placeholderText: '1234 1234 1234 1234',
            },
            cardExpiration: {
              labelText: 'Expiration date',
              placeholderText: 'MM/YY',
            },
            cardCVV: {
              labelText: 'Security code',
              placeholderText: 'CVV',
            },
            cardZipCode: {
              labelText: 'Zip code',
              placeholderText: '12345-6789',
            },
          },
	   // we'll cover styles, errorStyles, and field styles in the next section
          styles: {...},
          errorStyles: {...},
        },
      });

paymentSheetElement.mount('card-tokenization-form-container')

Step 2: Style a ForagePaymentSheetElement

Set the width and height on the Forage element’s parent container to adjust the size of the element, as in the following example.

<div id="card-tokenization-form-container" style="width: 500px; height: 500px;"></div>

Three types of styles can be set on the ForagePaymentSheetElement.

styles
- Common styles that will propagate to all fields
errorStyles
- Applied when an invalid field’s blur event is called
- Removed when input is detected in an invalid field
field styles
- Styles specific to a field. Takes precedence over any common styles on a field.

Style settings can affect the field's input and label styles using the inputStyles and labelStyles objects, respectively.

Pass the styles when creating the ForagePaymentSheetElement.

const paymentSheetElement = forage.create('payment_sheet', {
        paymentSheet: {
          paymentType: 'HSAFSA',
          fields: {
            cardHolderName: {
              labelText: 'Full name',
              placeholderText: 'John Doe',
              // styles scoped only to this field and will override common styles
              styles: {
                inputStyles: {
                  border: '2px solid #024230',
                },
                labelStyles: {
                  textAlign: 'center',
                },
              },
            },
            cardNumber: {...},
            cardExpiration: {...},
            cardCVV: {...},
            cardZipCode: {...},
          },
          // common styles that will propagate to all fields
          styles: {
            inputStyles: {
              border: '3px solid black',
              borderRadius: '8px',
              outline: 'none',
              padding: '10px',
            },
            labelStyles: {
              fontSize: '1rem',
              fontWeight: 'bold',
            },
          },
          // error styles to use when fields are invalid onBlur
          errorStyles: {
            inputStyles: {
              borderColor: 'red',
            },
          },
        },
      });

Step 3: Set up text input validation

Forage validates a Payment Sheet’s input as the user types. To notify users of input validation errors, you’ll need to listen for the change event on a front-end Forage Element to validate the customer’s input and to enable the submit function, as in the example below.

paymentSheetElement.on('change', (event) => {
  if (event.error) {
    // All payment sheet completion errors are provided in error.message
    console.log(event.error.message); // {"message":{"cardNumber":"invalidCardNumber"}}
  } else {
    // hide validation error
    setValidationMessage('');
  }

  if (event.complete) {
    // enable submit button
    setDisabled(false);
  }
});

Fields are not evaluated until the user touches them. Below are the possible errors in each field.

Field	Possible invalid errors
`cardHolderName`	`incomplete`
`cardNumber`	`incomplete`, `invalidCardNumber`
`cardExpiration`	`incomplete`, `invalidDate`
`cardCVV`	`incomplete`
`cardZipCode`	`incomplete`

Step 4: Tokenize an HSA/FSA payment method

Call the tokenizeCard() submit method from your front-end to submit a customer’s HSA/FSA Card number to Forage (Submit a ForagePaymentSheetElement).
1. tokenizeCard() creates a Forage PaymentMethod object that represents the HSA/FSA Card number. It also returns a ref for the PaymentMethod.
2. Handle potential errors (Forage JS errors).

async function submitCardNumber() {
  try {
    const tokenizationResult = await forage.tokenizeCard(
      paymentSheetElement
    )
    return tokenizationResult
  } catch (error) {
    const { httpStatusCode, message, code } = error ?? {}
  }
}

Next steps: Authorize and Capture a payment

Follow the Authorize and Capture an HSA/FSA payment guide from this point to complete the payment.

JS HSA/FSA Quickstart