---
updatedAt: 2026-06-02T20:51:39.000Z
agentTools:
  projectIndex: https://docs.joinforage.app/llms.txt
---

# 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](https://apps.apple.com/us/app/forage-ebt-balance-savings/id6742527220) or [Android](https://play.google.com/store/apps/details?id=com.foragetechnologycorp.forage) 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](#submit-the-element) to create the balance check.

#### Parameters

| Parameter                                          | Type   | Description                                                                                                        |
| -------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
| `collect_pin`<p style={{color:"red"}}>required</p> | string | The constant string `collect_pin`.                                                                                 |
| `elementOptions`                                   | object | A set of optional configuration settings for the `ForagePinElement`. Refer to [`elementOptions`](#elementoptions). |

##### `elementOptions`

| Field   | Type   | Description                                                                                                                                                                                                                                               |
| ------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `style` | object | An object that sets certain CSS properties for the ForagePinElement. Current supported key-value pairs include:<br /><br />- `borderColor`: A string that indicates the border color<br /><br />- `borderWidth`: A string that specifies the border width |

#### Example

```javascript
const balanceElement = forage.create('collect_pin')
```

> 📘 Mount The EBT Element
>
> After creating the `EBT Element`, call the [`mount()`](https://docs.joinforage.app/reference/mount) method to attach it to the DOM. Refer to the [`EBT Element` lifecycle](https://docs.joinforage.app/reference/ebt-elements#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

|                                                         | Type   | Description                                                                                                                                 |
| ------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `ForagePinElement`<p style={{color:"red"}}>required</p> | object | The object created in response to calling the method that [creates a balance check element](#create-a-forageebtbalanceelement).             |
| `paymentMethodRef`<p style={{color:"red"}}>required</p> | string | A string identifier that refers to an instance in Forage's database of a PaymentMethod, which is a tokenized representation of an EBT Card. |

#### Example

```javascript
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:

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

##### Object fields

|             | Type                                                                                | Description                                                                             |
| :---------- | :---------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------- |
| `ebt[snap]` | string                                                                              | The available SNAP balance on the customer's EBT Card, represented as a numeric string. |
| `ebt[cash]` | string                                                                              | The available EBT Cash balance left on the EBT Card, represented as a numeric string.   |
| `updated`   | [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string | The date-time when the funds in the account last changed                                |

#### Failure response

If the EBT balance check fails, then the `Promise` rejects with a [`ForageError`](https://docs.joinforage.app/reference/errors) object that describes the failure, as in the following example:

```javascript
{
  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:

```javascript
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](https://docs.joinforage.app/docs/forage-js-quickstart#check-and-display-the-balance-of-an-ebt-card) in the Forage JS quickstart, and listen for the "change" event's complete value to [enable the button as in this snippet](https://docs.joinforage.app/reference/change#listen-for-complete).
>
> 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.

# Sibling pages

* [Tokenize an EBT Card](https://docs.joinforage.app/reference/store-an-ebt-card.md)
* [Capture an EBT payment](https://docs.joinforage.app/reference/capture-ebt-payment.md)
* [Collect an EBT Card PIN for server-side payment capture](https://docs.joinforage.app/reference/collect-an-ebt-card-pin-for-server-side-payment-capture.md)
* [Tokenize a Payment Sheet](https://docs.joinforage.app/reference/tokenize-a-payment-sheet.md)