HomeGuidesReference
Log In
Reference

Tokenize a Payment Sheet

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

ParameterTypeDescription
payment_sheet

required

stringThe constant string payment_sheet.
paymentSheetConfig

required

objectConfiguration settings for the ForagePaymentSheetElement. Refer to paymentSheetConfig.
paymentSheetConfig
FieldTypeDescription
paymentSheet

required

objectAn object that sets the configuration of the payment sheet's paymentType, input labels, placeholder text, styles, and more. Refer to paymentSheet
paymentSheet
FieldTypeDescription
paymentType

required

stringThe constant string HSAFSA
styles

required

objectAn 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

objectAn 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

objectAn 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
FieldTypeDescription
labelText

required

stringThe text to display in the label element.
placeholderText

optional

stringThe 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

TypeDescription
ForagePaymentSheetElement

required

objectThe object returned by calling forage.create('payment_sheet', {...}).
optionsobjectA set of optional configuration settings for the Card. Refer to options.
options
TypeDescription
reusablebooleanWhether 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

TypeDescription
refstringA string identifier that refers to an instance in Forage's database of a PaymentMethod, a tokenized representation of a Credit Card.
typestringA constant credit string.
reusablebooleanWhether the payment method can be reused. If false, then the payment method can only be used for a single transaction.
cardobjectAn object with information about the card, as detailed in the card response fields.
card fields
TypeDescription
brandstringThe brand of the card used.
exp_monthnumberThe card's expiration month.
exp_yearnumberThe card's expiration year.
is_hsa_fsabooleantrue if the card is eligible for HSA/FSA purchases. Otherwise false.
psp_customer_idstringThe Stripe identifier for the customer.
payment_method_idstringA unique identifier for a Stripe PaymentMethod that represents a customer's credit/debit payment instrument.
last_4stringThe last four digits of the card number.
createdISO 8601 date-time stringThe 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.