Forage JS

You can use the Forage JS SDK to process EBT payments in your web application.

Features

• Native UI component, called an EBT Element, for securely collecting and tokenizing a customer’s EBT Card number (also known as EBT PAN)
• EBT Element for securely collecting a customer’s EBT PIN
• Built-in EBT PAN validation
• Control over the styling of a native EBT checkout experience
• Methods that securely collect and tokenize a PAN, perform a balance check, and capture a payment

Prerequisites

• Before using the Forage JS SDK, make sure that you’ve met all of the prerequisites for working with Forage.
• Set up your development environment

Starter code and EBT Element life cycle

✅

For comprehensive instructions, refer to the complete Forage JS documentation.

The EBT Element lifecycle contains the following steps:

1. Initialize
2. Create
3. Attach event listeners
4. Mount
5. Submit
6. Destroy

Step 1: Initialize

const forage = Forage({
  fnsNumber: '1234567',
  sessionToken:
    'sandbox_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhIjo0MiwiZXhwIjoxNjc2OTg2ODM1fQ.7KLvDpM9WHRD4pKCYr0rOy2kM0hVf3bwtZEAOZJrJ1w',
  // NOTE: The following line is for testing purposes only and should not be used in production.
  // Please replace this line with a real hashed customer ID value.
  customerId: btoa(Math.random().toString()),
  appearance: {
    variables: {
      borderRadius: '8px'
    }
  }
})

Refer to the Initialize Forage JS docs for complete documentation.

Step 2: Create an EBT Element

To create an EBT Element, invoke the create() method on the instance of the Forage object, passing in the usecase that corresponds to the target element type.

The following example creates a ​​ForageEbtCardNumberElement that a customer can use to securely input their EBT Card number:

const tokenizeEbtCardElement = forage.create('ebt_card_tokenize_number')

Step 3: Attach event listeners

The following example displays a message if there's an event.error on change:

tokenizeEbtCardElement.on('change', (event) => {
  const explainErrorSpan = document.getElementById('explain-error')
  if (event.error) {
    // show validation error to customer
    explainErrorSpan.textContent = event.error.message
  } else {
    // hide validation error
    explainErrorSpan.textContent = ''
  }
})

Step 4: Mount the EBT Element

Mount the element to the DOM:

tokenizeEbtCardElement.mount('card-entry-container')

Step 5: Submit the EBT Element

Call the EBT Element's submit() method to securely transmit the customer input to Forage, as in the example below:

try {
  const tokenizedEbtCardResult = await forage.tokenizeEbtCardNumber(
    tokenizeEbtCardElement
  )
  const { ref: paymentMethodRef, type, balance, card } = tokenizedEbtCardResult
} catch (forageErr) {
  if (forageErr?.errors?.length) {
    const [error] = forageErr.errors
    // unpack the first error
    const { httpStatusCode, message, code } = error ?? {}
  }
}

Step 6: Destroy the EBT Element

tokenizeEbtCardElement.destroy()

Next steps

• Explore Forage JS reference docs