Check the balance of an EBT Card

✅

Looking for the Forage mobile app?

Get instant EBT balance checks and access to exclusive grocery deals—download Forage on iOS or Android and start saving today.

🚧

FNS requirements for balance inquiries

FNS prohibits balance inquiries on sites that offer guest checkout. Skip implementing this EBT Element flow if your site offers a guest checkout option.

If your site doesn't offer guest checkout, then it's up to you whether or not to add a balance inquiry feature. No FNS regulations apply.

Create a ForagePinElement

forage.create('collect_pin')

This Forage method displays an input field that collects a customer’s four-digit EBT Card PIN in order to check the account balance. Forage does not store the PIN.

Returns a ForagePinElement that is passed to the submit method to create the balance check.

Parameters

elementOptions

Example

const balanceElement = forage.create('collect_pin')

📘

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 ForagePinElement

forage.checkBalance(ForagePinElement, paymentMethodRef)

This Forage method executes a balance check when passed the below parameters:

Parameters

Example

try {
  const balanceResult = await forage.checkBalance(
    balanceElement,
    paymentMethodRef
  )
  const { ebt, updated } = balanceResult
  const { snap, cash } = ebt ?? {}
} catch (error) {
  const { httpStatusCode, message, code } = error ?? {}
}

forage.checkBalance(ForagePinElement, paymentMethodRef) returns a Promise.

Success response

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

{
  ebt: {
    snap: '100.00',
    cash: '100.00',
  },
  updated: '2021-06-16T00:11:50.000000Z-07:00'
}

Object fields

Failure response

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

{
  httpStatusCode: 400,
  code: 'ebt_error_14',
  message: 'Invalid card number - Re-enter Transaction'
}

You can catch and handle specific errors with switch statements in the function call, as in the below snippet:

try {
  const paymentCaptureResult = await forage.checkBalance(
    balanceElement,
    paymentMethodRef
  )
  // handle successful checkBalanceResult
} catch (error) {
  const { code, details, httpStatusCode, message } = error ?? {}

  switch (code) {
    case 'ebt_error_14':
    // handle invalid card number!
    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.