Tokenize a Card

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

elementOptions

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

options

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

card fields

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.