Create a `ForageCardElement`

`forage.create('tokenize_card')`

This Forage method displays an input field that collects a customer's EBT Card number, also known as their Personal Account Number (PAN), in order to tokenize the card and save it for future use.

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

Parameters

Parameter	Type	Description
`tokenize_card` required	string	The constant string `tokenize_card`.
`elementOptions`	object	A set of optional configuration settings for the `ForageCardElement`. Refer to `elementOptions`.

`elementOptions`

Field	Type	Description
`style`	object	An object that sets certain CSS properties for the `ForageCardElement`. Current supported key-value pairs include: - `borderColor`: A string that indicates the border color - `borderWidth`: A string that specifies the border width

Example

const tokenizeCardElement = forage.create('tokenize_card')

📘
Mount The EBT Element
After creating the EBT Element, call the mount() method to attach it to the DOM. Refer to the EBT Element lifecycle for more details.

Submit a `ForageCardElement`

`forage.tokenizeCard(ForageCardElement, options?)`

This Forage method tokenizes an EBT Card number.

Parameters

	Type	Description
`ForageCardElement` required	object	The object returned by calling `forage.create('tokenize_card')`.
`options`	object	A set of optional configuration settings for the EBT 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(
    tokenizeCardElement,
    { reusable: true }
  )
  const { ref: paymentMethodRef, type, balance, card } = tokenizationResult
} catch (error) {
  const { httpStatusCode, message, code } = error ?? {}
}

forage.tokenizeCard(ForageCardElement) returns a Promise.

Success response

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

{
  ref: 'ac47392bb1',
  type: 'ebt',
  balance: {
    ebt: {
      snap: '100.00',
      cash: '100.00'
    }
    updated: '2021-06-16T00:11:50.000000Z-07:00'
  },
  card: {
    last_4: '3456',
    created: '2023-07-10T17:21:23.346019-07:00',
    ebt: {
      usState: 'CA',
    }
  },
  customerId: '5b53e4786e73d3da67d04f1bfe5269f72684085a23034f6b55e6887dcdb76417'
}

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 an EBT Card.
`type`	string	A constant string; always `ebt` for Forage JS.
`balance`	object	The available SNAP and Cash balances on the EBT account associated with the EBT Card, the same as the object returned during a balance check.
`card`	object	An object with information about the card, as detailed in the card fields.
`customerId`	string	A unique ID for the end customer making the payment that you shared when you initialized Forage JS.
`reusable`	boolean	Whether the payment method can be reused. If `false`, then the payment method can only be used for a single transaction.

`card` fields

	Type	Description
`last_4`	string	The last four digits of the EBT Card number.
`created`	ISO 8601 date-time string	The date-time when the `card` object was created.
`ebt[usState]`	string \| null	A two-letter abbreviation for the US state where the card was issued.

Failure Response

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

{
  httpStatusCode: 400,
  code: 'unsupported_bin',
  message: 'You attempted to add a card from Guam or the Virgin Islands, where online EBT processing is not yet supported.'
}

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(
    tokenizeCardElement,
    { reusable: true }
  )
  const { ref: paymentMethodRef, type, balance, card } = tokenizationResult
  // handle successful tokenizeCard result
} catch (error) {
  const { code, details, httpStatusCode, message } = error ?? {}

  switch (code) {
    case 'unsupported_bin':
    // handle unsupported_bin!
    break
    case 'ebt_error_55':
    // entered the wrong PIN!
    break
    default:
    // handle unexpected errors
  }
}

⚠️
Enable A "Submit" Button For Customer Input
Find an example submit function in the Forage JS quickstart, and 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.