---
title: "Create a Custom Balance Check Session"
method: POST
path: "/api/balance_sessions/"
tags: ["Custom Sessions"]
---

# Create a Custom Balance Check Session

`POST /api/balance_sessions/`

> ⚠️ FNS Requirements
>
> FNS prohibits balance inquiries on sites and apps that offer guest checkout. Do not use this endpoint if your customers can opt for guest checkout.
>
> If guest checkout is not an option, then it's up to you whether or not to add a balance inquiry feature. No FNS regulations apply.

A `POST` request to `/balance_sessions/` initiates a `Session` of the Custom Balance Check Forage UI.

Pass the Forage [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods) `ref`, the hashed reference ID that represents the EBT Card, as the `payment_method` param in the request body.

The response payload represents the [Custom Balance Check `Session`](https://docs.joinforage.app/reference/forage-sessions#custom-balance-check-session). The `redirect_url` value is the URL that launches the front-end, customer-facing Forage UI. Point a customer to this URL to enter their PIN to perform a secure balance inquiry.

If PIN entry is successful, then Forage points the customer to the `success_redirect_url` specified in the request body. Forage directs them to the `cancel_redirect_url` if they cancel the balance inquiry via the Forage UI.

> 📘 Retrieve Customer EBT Card Balance
>
> After a customer completes the Forage UI and is pointed to your `success_redirect_url`, send a `GET` to [`/api/payment_methods/{payment_method_ref}/`](https://docs.joinforage.app/reference/get-payment-method) and inspect the `balance` field of the response to retrieve their EBT Card balance.

See these guide for additional information:

- [How Custom integrations work (Check the balance of an EBT account)](https://docs.joinforage.app/docs/custom#check-the-balance-of-an-ebt-account)
- [Custom Quickstart](https://docs.joinforage.app/docs/custom-quickstart)
- [Custom Balance Check `Session` payload](https://docs.joinforage.app/reference/forage-sessions#custom-balance-check-session)

## Request body

- BalanceSessionRequest — This object starts a Custom Balance Check Forage `Session`, used to check the balance of an already-stored Forage `PaymentMethod`.
  - `payment_method` string, required — The unique, hashed reference ID to the Forage [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods) instance that represents the EBT Card. The `type` of the `PaymentMethod` must be `ebt`, otherwise the API returns an error. Send a `POST` to [`/payment_methods/`](https://docs.joinforage.app/reference/create-payment-method) to create a `PaymentMethod`.
  - `success_redirect_url` string, required — The URL that Forage redirects your customer to if the balance inquiry is successful.
  - `cancel_redirect_url` string, required — The URL that Forage redirects your customer to if the balance inquiry is canceled.

## Response `200`

__OK__ - Success

- BalanceSessionResponse — This object starts a Custom Balance Check Forage `Session`, used to check the balance of an already-stored Forage `PaymentMethod`.
  - `payment_method` string, required — The unique, hashed reference ID to the Forage [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods) instance that represents the EBT Card. The `type` of the `PaymentMethod` must be `ebt`, otherwise the API returns an error. Send a `POST` to [`/payment_methods/`](https://docs.joinforage.app/reference/create-payment-method) to create a `PaymentMethod`.
  - `success_redirect_url` string, required — The URL that Forage redirects your customer to if the balance inquiry is successful.
  - `cancel_redirect_url` string, required — The URL that Forage redirects your customer to if the balance inquiry is canceled.
  - `ref` string — A unique identifier for the Custom Balance Check `Session`. Pass this `ref` in a `GET` to [`/balance_sessions/{session_ref}/`](https://docs.joinforage.app/reference/get-custom-balance-check-session) to inspect the `Session` properties.
  - `redirect_url` string, url — The URL that launches the Forage Session UI. Point a customer to this URL when they are ready to enter their EBT Card PIN to perform a secure balance inquiry.
  - `previous_errors` object[] — An array with information about the error.
    - `code` string — A short string that represents the error.
    - `message` string — A developer-facing message with more details about the error, not to be displayed to customers.
    - `source` object
      - `resource` string — The type of the Forage resource involved in the error.
      - `ref` string — If applicable, the ten character reference hash of the Forage resource that caused the error. An empty string if no specific individual resource was involved.
    - `details` object — Additional details about the error, if applicable.

## Other responses

- `400` — __Bad request__ - The request was not accepted because of an error in the request body or path.
- `401` — Unauthorized
- `409` — Conflict
- `423` — __Locked__ - The request could not be completed because the target resource is currently locked.
- `429` — Too Many Requests
- `500` — Internal Server Error

---

[API](https://skmtc.dev/joinforage/apis/forage-payments-api.md) · [All operations](https://skmtc.dev/joinforage/apis/forage-payments-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/joinforage/forage-payments-api/revisions/4b7212706fae/schema)