EBT Balance Link Getting Started

Getting started guide for linking an EBT account.

πŸ“˜

API Secret and Webhook ID

You'll need an API secret and your organization ID to complete this integration. Neither are required in the sandbox.

Overview

The EBT Balance Link flow lets you link your customer's EBT account to your product. This allows you to verify that they receive SNAP or EBT cash assistance and enables the display of current balances and transaction history. Benny offers two link options:

  1. Via the Benny SDK (available on Android, iOS, and React Native) to collect the customer's EBT account login credentials. Account verification and login are synchronous. The SDK also supports EBT account creation if the customer doesn't already have an account with their state website.
  2. Via API-only. Your client UI collects the login credentials Benny verifies asynchronously, emitting a webhook event when verification completes. Account creation is not supported via API access, given the sensitive fields required, such as the EBT card number and PIN.

Linking

All 50 States, along with the District of Columbia, are supported

SDK

Leveraging Benny's mobile SDKs offers the best customer experience and ensures that Benny only collects sensitive login information. As an overview:

An overview of the SDK link flow. Dotted lines are optional actions.

An overview of the SDK link flow. Dotted lines are optional actions.

Integrate with Mobile SDKs

To start, review the linked documentation and integrate the SDKs with your mobile app:

  1. Android
  2. iOS
  3. React Native

Create a Temporary Link

All mobile SDKs must be initialized with a single-use temporary link generated by a serverside call to Benny's API. Call (SDK) Get temporary link to generate a temporary link token to pass to your mobile client and the Benny SDK.

The Benny SDK will guide the customer through linking their account.

Wait For Link Token

On a successful link via the SDK flow:

  1. The long-lived link token and account holder metadata will be emitted via a webhook event.
  2. Also, via a callback, the mobile SDK will emit the long-lived link token if you do not wish to listen for webhook events.

Webhooks

The webhook event includes account holder metadata as well as the long-lived token.

{
  "payload": {
    "temporary_link": "temp_s76o1azllg3qe4j9hz2zm6ylt",
    "token": "tkn_n60unr8p8z0jnk4cqa4q5hi2",
    "account_id": "acc_vn8ndtymq3bqlcot4tmo31gt",
    "account_holder": {
      "name": "John Smith",
      "address": "123 Main Street, Apt 1, New York, NY, 10012",
      "balances": {
        "cash": 0,
        "snap": 1023
      },
      "last_transaction_date": "2024-01-23"
    }
  },
  "type": "ebt.link.client.success"
}

SNAP Program Verification Only

πŸ‘

SNAP Program Verification Only

If you are not interested in fetching the customer's EBT balances or transaction history and are only interested in verifying that they receive SNAP benefits, the integration is complete.

Call Deactivate a link token to delete the customer's token and associated credential data.

API-Only

🚧

Optional

If you've integrated using the Benny SDK, skip ahead to Linked Account.

Your client UI will collect the benefit owner's state and login credentials, which Benny will verify asynchronously and tokenize for later use.

An overview of the API-only link flow. Dotted lines are optional actions.

An overview of the API-only link flow. Dotted lines are optional actions.

Creating a Temporary Link

A benefit owner's state code, login username, and password are required to create a temporary link. Obtain them from your customer and call the Create temporary link endpoint. This endpoint is responsible for determining if the credentials provided are correct, and if so, returns a temporary link that you must exchange for a long-living token.

Challenge Questions

A small set of states will prompt for a challenge question response when logging in. The (API) Create temporary link can optionally accept a list of challenge question responses if you wish to collect this in your client UI. If the customer login credentials are correct, but a challenge question response is required, this will be emitted in a webhook event.

Link Metadata

Link metadata is returned when exchanging a valid temporary link for a long-living token. This includes the account holder's first and last name and the maximum duration of the long-living token is valid before a password reset is required. Not all accounts require a password reset, though.

Webhooks

When the temporary link is successfully created, a "success" webhook event is emitted:

{
  "payload": {
    "temporary_link_id": "temp_s76o1azllg3qe4j9hz2zm6ylt",
  },
  "type": "ebt.link.success"
}

On failure due to invalid credentials (i.e., the username and password), a failure webhook event is emitted:

{
  "payload": {
    "temporary_link_id": "temp_s76o1azllg3qe4j9hz2zm6ylt",
    "is_account_locked": false,
    "is_invalid_credentials": true,
  },
  "type": "ebt.link.failure"
}

On failure due to valid credentials but a missing or invalid challenge question answer response, a failure webhook event is emitted:

{
  "payload": {
    "temporary_link_id": "temp_s76o1azllg3qe4j9hz2zm6ylt",
    "is_invalid_challenge_question_answer": true,
    "challenge_question_type": "BIRTH_CITY"
  },
  "type": "ebt.link.failure"
}

When a long-living link is deactivated, a webhook is emitted:

{
  "payload": {
    "account_id": "acc_tkero8aci1idybyxiak8tx0a",
    "link_token": "tkn_n60unr8p8z0jnk4cqa4q5hi2"
  },
  "type": "ebt.link.deactivated"
}

See our event catalog for more information. Webhooks can be created and tested via our developer dashboard.

Exchanging a Temporary Link

A temporary link must be exchanged for a long-living link token, as a temporary link will expire after 30 minutes. To exchange the temporary link for a link token, use the Link exchange endpoint. A successful response will return your link token.

Linked Account

Once an account is linked, the long-living link token can fetch balance and transaction information. Or if you do not need this information, as only a single successful link was required, you can deactivate the link token with Deactivate a link token

Get Balance and Transactions

Benny will periodically poll linked customer accounts throughout the day to ensure that balance and transaction data are current.

To fetch the EBT SNAP and cash balances, use the Get balance endpoint. As a benefit owner can have any combination of EBT SNAP or EBT cash balances, both balances are optionally returned.

To fetch transactions, use the Get transactions endpoint. A paginated list of transaction data will be returned. Note that transaction data is stored for 30 to 90 days, depending on the state, and transaction information at later dates is unavailable.

All monetary amounts are stored in cents.

Webhook Events

When the SNAP or EBT cash balance is updated, a webhook is emitted:

{
  "type": "ebt.balance.change",
  "payload": {
    "account_id": "acc_tkero8aci1idybyxiak8tx0a",
    "cash_balance": {
      "old_cash_balance_cents": 1000,
      "new_cash_balance_cents": 500
    },
    "snap_balance": {
      "old_snap_balance_cents": 1500,
      "new_snap_balance_cents": 1000
    }
  }
}

When there is a new transaction or an update to a transaction, a webhook is emitted:

{
  "payload": {
    "account_id": "acc_tkero8aci1idybyxiak8tx0a"
  },
  "type": "ebt.transaction.change"
}

What’s Next

Review the EBT sandbox and send test requests.