HomeGuidesReference
Log In
Reference

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

ParameterTypeDescription
tokenize_card

required

stringThe constant string tokenize_card.
elementOptionsobjectA set of optional configuration settings for the ForageCardElement. Refer to elementOptions.
elementOptions
FieldTypeDescription
styleobjectAn 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')

👍

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

TypeDescription
ForageCardElement

required

objectThe object returned by calling forage.create('tokenize_card').
optionsobjectA set of optional configuration settings for the EBT 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(
    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

TypeDescription
refstringA string identifier that refers to an instance in Forage's database of a PaymentMethod, a tokenized representation of an EBT Card.
typestringA constant string; always ebt for Forage JS.
balanceobjectThe available SNAP and Cash balances on the EBT account associated with the EBT Card, the same as the object returned during a balance check.
cardobjectAn object with information about the card, as detailed in the card response fields.
customerIdstringA unique ID for the end customer making the payment that you shared when you initialized Forage JS.
reusablebooleanWhether the payment method can be reused. If false, then the payment method can only be used for a single transaction.
card fields
TypeDescription
last_4stringThe last four digits of the EBT Card number.
createdISO 8601 date-time stringThe date-time when the card object was created.
ebt[usState]string | nullA two-letter abbreviation for the US state where the card was issued, with the exception of the Dakotas denoted as ND/SD.

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.