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

ParameterTypeDescription
collect_pin

required

stringThe constant string collect_pin.
elementOptionsobjectA set of optional configuration settings for the ForagePinElement. Refer to elementOptions.
elementOptions
FieldTypeDescription
styleobjectAn object that sets certain CSS properties for the ForagePinElement. Current supported key-value pairs include:

- borderColor: A string that indicates the border color

- borderWidth: A string that specifies the border width

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.

Parameters

TypeDescription
ForagePinElement

required

objectThe object created in response to calling the method that creates a balance check element.
paymentMethodRef

required

stringA string identifier that refers to an instance in Forage's database of a PaymentMethod, which is a tokenized representation of an EBT Card.

Example

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

Returns

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

On success, the Promise resolves with an object that contains the following fields:

TypeDescription
ebt[snap]stringThe available SNAP balance on the customer’s EBT Card, represented as a numeric string.
ebt[cash]stringThe available EBT Cash balance left on the EBT Card, represented as a numeric string.
updatedISO 8601 date-time stringThe date-time when the funds in the account last changed.

Example return value

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

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.

If the EBT balance check fails, then the Promise rejects with a ForageError object that describes the failure.