Check the balance of an EBT Card

🚧

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')

👍

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.