📘

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 allows you to create a long-living "link" between your product and your customer's EBT account. As long as the link is valid, you can receive the latest EBT balances and transaction history.

The Benny SDK (available on Android, iOS, and React Native) securely collects the customer's EBT account login credentials. The SDK also supports EBT account creation if the customer doesn't already have an account with their state's website.

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:

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.

We recommend including in this request your organization's representation of the customer ID, i.e., the "External ID". The external ID and the link token will be returned via a webhook event on success. 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",
    "external_id": "ba6bfca8-3bed-4b11-ba2d-4bad2a042593",
    "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",
      "card_last_four": "1234"
    }
  },
  "type": "ebt.link.client.success"
}

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 event 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 event is emitted with the updated transactions:

{
  "payload": {
    "account_id": "acc_tkero8aci1idybyxiak8tx0a",
    "transactions": [
      {
        "amount": 3600,
        "balanceType": "SNAP",
        "currencyCode": "USD",
        "date": "2024-01-05T00:00:00Z",
        "id": "txn_clr10cy59000k08l5e0wg5hrw",
        "transactionType": "FUND_LOAD"
      },
      {
        "amount": -500,
        "balanceType": "SNAP",
        "currencyCode": "USD",
        "date": "2024-01-04T00:37:56Z",
        "id": "txn_clr0zzpcj000108l52e7n6mgk",
        "merchant": "Berry's Bazaar",
        "merchantLocation": "456 Broadway, New York, NY",
        "transactionType": "PURCHASE"
      }
    ]
  },
  "type": "ebt.transaction.change"
}

When a long-living link is deactivated, a webhook event is emitted.

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

For more information, see our event catalog. Webhooks can be created and tested via our developer dashboard