Create a `ForagePaymentSheetElement`

`forage.create('payment_sheet', {...})`

This Forage method displays an input field that collects a customer’s HSA/FSA Card number in order to tokenize the card and save it for future use.

Returns a ForagePaymentSheetElement that is passed to the corresponding submit method to store a secure reference to the card number.

Parameters

Parameter	Type	Description
`payment_sheet` required	string	The constant string `payment_sheet`.
`paymentSheetConfig` required	object	Configuration settings for the `ForagePaymentSheetElement`. Refer to `paymentSheetConfig`.

`paymentSheetConfig`

Field	Type	Description
`paymentSheet` required	object	An object that sets the configuration of the payment sheet's `paymentType`, input labels, placeholder text, styles, and more. Refer to paymentSheet

`paymentSheet`

Field	Type	Description
`paymentType` required	string	The constant string `HSAFSA`
`styles` required	object	An object that propagates styles to all fields in the `ForagePaymentSheetElement`. Current supported key-value pairs include: - `inputStyles`: `CSSStyleDeclaration` that will be applied to all input elements. - `labelStyles`: `CSSStyleDeclaration` that will be applied to all label elements.
`errorStyles` required	object	An object that propagates error styles to all fields in the `ForagePaymentSheetElement` when invalid input is detected on input blur. These styles are removed when input is detected. Current supported key-value pairs include: - `inputStyles`: `CSSStyleDeclaration` that will be applied to all input elements. - `labelStyles`: `CSSStyleDeclaration` that will be applied to all label elements.
`fields` required	object	An object defining configurations scoped to each field in the `ForagePaymentSheetElement`. Key-value pairs include: - `cardHolderName`: `fieldConfig` - `cardNumber`: `fieldConfig` - `cardExpiration`: `fieldConfig` - `cardCVV`: `fieldConfig` - `cardZipCode`: `fieldConfig`

`fieldConfig`

Field	Type	Description
`labelText` required	string	The text to display in the label element.
`placeholderText` optional	string	The text to display in the input element placeholder.

Example

const foragePaymentSheet = forage.create('payment_sheet', {
        paymentSheet: {
          paymentType: 'HSAFSA',
          // common styles propagating to all fields
          styles: {
            inputStyles: {
              border: '3px solid black',
              borderRadius: '8px',
              padding: '10px',
            },
            labelStyles: {
              fontSize: '1rem',
              fontWeight: 'bold',
            },
          },
          // error styles to use when fields are invalid on blur event
          errorStyles: {
            inputStyles: {
              borderColor: 'red',
            },
          },
          fields: {
            cardHolderName: {
              labelText: 'Full name',
              placeholderText: 'John Doe',
              // styles scoped to the field
              styles: {
                inputStyles: {
                  border: '2px solid blue',
                },
              },
            },
            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',
            },
          },
        },
      })

📘
Mount The ForagePaymentSheetElement
After creating the ForagePaymentSheetElement, call the mount() method to attach it to the DOM. This element uses the same lifecycle as the EBT Elements. Refer to the EBT Element lifecycle for more details.

Submit a `ForagePaymentSheetElement`

`forage.tokenizeCard(ForagePaymentSheetElement, options?)`

This Forage method tokenizes a Payment Sheet card.

Parameters

	Type	Description
`ForagePaymentSheetElement` required	object	The object returned by calling `forage.create('payment_sheet', {...})`.
`options`	object	A set of optional configuration settings for the Card. Refer to options.

options

	Type	Description
`reusable`	boolean	Whether the payment method can be reused. If `false`, then the payment method can only be used for a single transaction. Defaults to `true` if no `options` parameter is provided.

Example

try {
  const tokenizationResult = await forage.tokenizeCard(
    foragePaymentSheet,
    { reusable: true }
  )
  const { ref, type, card } = tokenizationResult
} catch (error) {
  const { httpStatusCode, message, code } = error ?? {}
}

forage.tokenizeCard(ForagePaymentSheetElement) returns a Promise.

Success response

On success, the Promise resolves with an object, as in the following:

{
  ref: 'ac47392bb1',
  type: 'credit',
  reusable: true,
  card: {
    brand: 'visa',
    exp_month: 12,
    exp_year: 2034,
    last_4: '3456',
    is_hsa_fsa: true,
    psp_customer_id: 'cus_SwmG7uYElJTytO',
    payment_method_id: 'pm_1S0si1P4HzVVeE0muBq9X46u',
    last_4: '3456',
    created: '2023-07-10T17:21:23.346019-07:00',
  },
}

Object fields

	Type	Description
`ref`	string	A string identifier that refers to an instance in Forage's database of a PaymentMethod, a tokenized representation of a Credit Card.
`type`	string	A constant `credit` string.
`reusable`	boolean	Whether the payment method can be reused. If `false`, then the payment method can only be used for a single transaction.
`card`	object	An object with information about the card, as detailed in the card response fields.

`card` fields

	Type	Description
`brand`	string	The brand of the card used.
`exp_month`	number	The card's expiration month.
`exp_year`	number	The card's expiration year.
`is_hsa_fsa`	boolean	`true` if the card is eligible for HSA/FSA purchases. Otherwise `false`.
`psp_customer_id`	string	The Stripe identifier for the customer.
`payment_method_id`	string	A unique identifier for a Stripe PaymentMethod that represents a customer's credit/debit payment instrument.
`last_4`	string	The last four digits of the card number.
`created`	ISO 8601 date-time string	The date-time when the `card` object was created.

Failure Response

If the card tokenization fails, then the Promise rejects with a ForageError object that describes the failure, as in the following example:

{
  httpStatusCode: 400,
  code: 'not_an_hsa_fsa_card',
  message: 'Not an HSA/FSA card'
}

You can catch and handle specific errors with switch statements in the function call, as in the below snippet:

try {
  const tokenizationResult = await forage.tokenizeCard(
    foragePaymentSheet,
    { reusable: true }
  )
  const { ref, type, card } = tokenizationResult
  // handle successful tokenizeCard result
} catch (error) {
  const { code, details, httpStatusCode, message } = error ?? {}

  switch (code) {
    case 'not_an_hsa_fsa_card':
    // handle not_an_hsa_fsa_card!
    break
    case 'user_error':
    // handle user_error!
    break
    default:
    // handle unexpected errors
  }
}

⚠️
Enable A "Submit" Button For Customer Input
Listen for the "change" event’s complete value to enable the button as in this snippet.
Allow customers to progress on their own. Do not use complete to automatically perform an action like submitting the form or advancing the cursor to the next input field.