--- updatedAt: 2026-04-06T19:27:04.000Z agentTools: projectIndex: https://docs.joinforage.app/llms.txt --- # JS HSA/FSA Quickstart Use the Forage JavaScript SDK to accept HSA/FSA payments online. 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: 1. [Step 1: Initialize a ForagePaymentSheetElement](#step-1-initialize-a-foragepaymentsheetelement) 2. [Step 2: Style a ForagePaymentSheetElement](#step-2-style-a-foragepaymentsheetelement) 3. [Step 3: Set up text input validation](#step-3-set-up-text-input-validation) 4. [Step 4: Tokenize an HSAFSA payment method](#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](https://www.joinforage.com/contact) if you don't have one yet.) * [forage-js-sdk](https://www.npmjs.com/package/forage-js-sdk/v/1.3.0) package version 1.3.0 or later For more information, see: * [Payments API reference docs](https://docs.joinforage.app/reference/introduction) # 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. Payment form for HSA/FSA using the Forage JavaScript SDK with fields for card holder name, card number, expiration date, security code, and zip code. Powered by Forage logo shown below. Example HSA/FSA payment form. Create a parent container for the Forage Element, as in the following example: ```html
``` After [initializing Forage JS](https://docs.joinforage.app/docs/forage-js#step-1-initialize), create and add the `ForagePaymentSheetElement` component to your front-end checkout flow to collect a customer's HSA/FSA Card number ([Create a ForagePaymentSheetElement](https://docs.joinforage.app/reference/tokenize-a-payment-sheet#create-a-foragepaymentsheetelement)). ```javascript 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. ```html
``` Three types of styles can be set on the `ForagePaymentSheetElement`. 1. `styles` * Common styles that will propagate to all fields 2. `errorStyles` * Applied when an invalid field's blur event is called * Removed when input is detected in an invalid field 3. `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`. ```javascript 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](https://docs.joinforage.app/reference/change) on a front-end Forage Element to validate the customer's input and to enable the submit function, as in the example below. ```javascript 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 1. Call the `tokenizeCard()` submit method from your front-end to submit a customer's HSA/FSA Card number to Forage ([Submit a `ForagePaymentSheetElement`](https://docs.joinforage.app/reference/tokenize-a-payment-sheet#submit-a-foragepaymentsheetelement)). 1. `tokenizeCard()` creates a Forage [PaymentMethod object](https://docs.joinforage.app/reference/payment-methods#paymentmethod-object) that represents the HSA/FSA Card number. It also [returns](https://docs.joinforage.app/reference/store-an-ebt-card#success-response) a `ref` for the `PaymentMethod`. 2. Handle potential errors ([Forage JS errors](https://docs.joinforage.app/reference/forage-js-errors)). ```javascript 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](https://docs.joinforage.app/docs/enable-hsa-fsa-payments#authorize-and-capture-an-hsafsa-payment) guide from this point to complete the payment. ## Explore more resources * [Forage JS reference documentation](https://docs.joinforage.app/reference/js-sdk-reference) * [Forage API reference documentation](https://docs.joinforage.app/reference/introduction) # Sibling pages * [Enable HSA/FSA Payments](https://docs.joinforage.app/docs/enable-hsa-fsa-payments.md) * [iOS HSA/FSA Quickstart](https://docs.joinforage.app/docs/ios-hsa-fsa-quickstart.md)