--- updatedAt: 2026-05-07T18:17:26.000Z agentTools: projectIndex: https://docs.joinforage.app/llms.txt --- # Retrieve a Custom Balance Check Session > ⚠️ Check EBT Card Balance > > This endpoint does not return a customer's EBT Card balance. If you're looking for a customer's EBT Card balance, then send a `GET` to [`/api/payment_methods/{payment_method_ref}`](ref:get-payment-method), and inspect the `balance` response field. A `GET` request to `/balance_sessions/` retrieves the properties of a Custom Balance Check Session. Use this endpoint to inspect a `Session`'s `success_redirect_url` and `cancel_redirect_url` values. See these guides for additional information: - [Create a Custom Balance Check `Session`](ref:create-custom-balance-check-session) - [Custom Balance Check `Session` payload](ref:forage-sessions#custom-balance-check-session) - [How Custom integrations work (Check the balance of an EBT account)](doc:custom#check-the-balance-of-an-ebt-account) - [Custom Quickstart](doc:custom-quickstart) # OpenAPI definition ```json { "openapi": "3.0.0", "x-readme": { "explorer-enabled": false, "proxy-enabled": false }, "info": { "title": "Forage Payments API", "description": "The Forage Payments API is a REST API for processing Electronic Benefits Transfer (EBT) payments (SNAP and EBT Cash) in your e-commerce or in-store application.\n\nProcessing any EBT payment, or checking an EBT card's balance, requires the cardholder's PIN. Federal regulations require all PIN entry to happen through a PCI-compliant, USDA-approved interface. Forage provides that interface, so EBT PIN collection always happens through a Forage-hosted surface (Forage Checkout or a Forage SDK), never directly in your own form. Some endpoints (for example, capture and balance) are only reachable through that surface because they require PIN data in the request.\n\nEBT rarely covers an entire order: items like delivery fees and non-eligible products can't be paid with SNAP or EBT Cash. You decide how to handle the remaining balance (split tender) and any credit or debit processing alongside the EBT portion.\n\nForage offers four integration options. Pick the one that fits your platform and engineering resources:\n\n1. **Fully Hosted Checkout.** Forage processes EBT and credit/debit through a Forage-hosted Checkout UI. Lowest engineering effort, and Forage absorbs most error handling. See the [Fully Hosted Checkout guide](https://docs.joinforage.app/docs/fully-hosted).\n2. **Custom Checkout.** Forage processes EBT; you handle split tender, taxes, and credit/debit in your own checkout flow. Best when you want minimal changes to your existing UX. See the [Custom Checkout guide](https://docs.joinforage.app/docs/custom).\n3. **Online SDKs.** Client-side SDKs for [web](https://docs.joinforage.app/docs/forage-js), [iOS](https://docs.joinforage.app/docs/ios), and [Android](https://docs.joinforage.app/docs/android) that collect EBT PINs in your app while keeping you out of PCI scope.\n4. **POS Terminal SDK.** Accept in-person EBT payments on an Android POS device. See the [POS Terminal guide](https://docs.joinforage.app/docs/forage-terminal-android).\n\nAs a general principle, any data created by your requests, or by your customers on a Forage-hosted surface, is retrievable through GET requests to the appropriate resource.\n\nHave more questions? Use our [contact form](https://www.joinforage.com/get-in-touch) to reach our sales and engineering support teams.\n", "contact": { "name": "API Support", "email": "engineering@joinforage.com" }, "version": "2025-08-04" }, "externalDocs": { "description": "Forage documentation", "url": "https://docs.joinforage.app/" }, "servers": [ { "url": "https://{environment}.joinforage.app", "variables": { "environment": { "default": "api.sandbox", "enum": [ "api", "api.sandbox" ] } } } ], "security": [], "paths": { "/api/balance_sessions/{session_ref}/": { "parameters": [ { "name": "session_ref", "in": "path", "description": "A unique identifier for the Custom Balance Check Session, returned as the `ref` value in the response payload of the `POST` request that created the `Session`.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/BearerTokenHeader" }, { "$ref": "#/components/parameters/MerchantAccountHeader" } ], "get": { "tags": [ "Custom Sessions" ], "summary": "Retrieve a Custom Balance Check Session", "x-readme": { "code-samples": [ { "language": "curl", "code": "curl --request GET \\\n --url https://api.sandbox.joinforage.app/api/balance_sessions// \\\n --header 'Authorization: Bearer ' \\\n --header 'Merchant-Account: ' \\\n --header 'accept: application/json'\n" } ] }, "description": "> ⚠️ Check EBT Card Balance\n>\n> This endpoint does not return a customer's EBT Card balance. If you’re looking for a customer's EBT Card balance, then send a `GET` to [`/api/payment_methods/{payment_method_ref}`](https://docs.joinforage.app/reference/get-payment-method), and inspect the `balance` response field.\n\nA `GET` request to `/balance_sessions/` retrieves the properties of a Custom Balance Check Session.\n\nUse this endpoint to inspect a `Session`'s `success_redirect_url` and `cancel_redirect_url` values.\n\nSee these guides for additional information:\n\n- [Create a Custom Balance Check `Session`](https://docs.joinforage.app/reference/create-custom-balance-check-session)\n- [Custom Balance Check `Session` payload](https://docs.joinforage.app/reference/forage-sessions#custom-balance-check-session)\n- [How Custom integrations work (Check the balance of an EBT account)](https://docs.joinforage.app/docs/custom#check-the-balance-of-an-ebt-account)\n- [Custom Quickstart](https://docs.joinforage.app/docs/custom-quickstart)\n", "operationId": "View balance session", "security": [ { "OAuth2": [ "internal", "pinpad_only" ] } ], "responses": { "200": { "$ref": "#/components/responses/BalanceSession200" }, "400": { "description": "__Bad request__ - The request was not accepted because of an error in the request body or path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "examples": { "invalid_input_data": { "summary": "Invalid Input Data", "value": { "path": "/api/balance_sessions/{session_ref}/", "errors": [ { "code": "invalid_input_data", "message": "Query parameter missing or incomplete.", "source": { "resource": "Sessions", "ref": "{session_ref}" } } ] } }, "invalid_merchant_account": { "summary": "Invalid Merchant Account", "value": { "path": "/api/balance_sessions/{session_ref}/", "errors": [ { "code": "invalid_merchant_account", "message": "Merchant account Merchant ID not valid.", "source": { "resource": "Merchants" } } ] } }, "missing_idempotency_key": { "summary": "Missing Idempotency Key", "value": { "path": "/api/balance_sessions/{session_ref}/", "errors": [ { "code": "missing_idempotency_key", "message": "You must include a value for the IDEMPOTENCY-KEY header in your requests to this endpoint.", "source": { "resource": "Idempotency_Key" } } ] } }, "missing_merchant_account": { "summary": "Missing Merchant Account", "value": { "path": "/api/balance_sessions/{session_ref}/", "errors": [ { "code": "missing_merchant_account", "message": "No merchant account was provided.", "source": { "resource": "Merchants" } } ] } }, "unknown_fields_error": { "summary": "Unknown Fields Error", "value": { "path": "/api/balance_sessions/{session_ref}/", "errors": [ { "code": "unknown_fields_error", "message": "Unknown field(s) provided: {unknown_fields}", "source": { "resource": "Sessions" } } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "examples": { "expired_session_token": { "summary": "Expired Session Token", "value": { "path": "/api/balance_sessions/{session_ref}/", "errors": [ { "code": "expired_session_token", "message": "This token has expired", "source": { "resource": "Session_Token" } } ] } }, "invalid_token": { "summary": "Invalid Token", "value": { "path": "/api/balance_sessions/{session_ref}/", "errors": [ { "code": "invalid_token", "message": "Incorrect authentication credentials.", "source": { "resource": "Accounts", "ref": "" } } ] } } } } } }, "404": { "description": "__Not Found__ - The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "example": { "path": "/api/balance_sessions/{session_ref}/", "errors": [ { "code": "resource_not_found", "message": "Balance session with ref {session_ref} does not exist for current Merchant with FNS {fns_number}", "source": { "resource": "Sessions", "ref": "{session_ref}" } } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "examples": { "too_many_requests": { "summary": "Too Many Requests", "value": { "path": "/api/balance_sessions/{session_ref}/", "errors": [ { "code": "too_many_requests", "message": "Request was throttled, please try again later.", "source": { "resource": "Sessions", "ref": "" } } ] } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "examples": { "unknown_server_error": { "summary": "Unknown Server Error", "value": { "path": "/api/balance_sessions/{session_ref}/", "errors": [ { "code": "unknown_server_error", "message": "Unknown exception from EBT network", "source": { "resource": "Unknown" } } ] } } } } } } } } } }, "components": { "schemas": { "ErrorsArray": { "type": "array", "description": "An array with information about the error.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "A short string that represents the error." }, "message": { "type": "string", "description": "A developer-facing message with more details about the error, not to be displayed to customers." }, "source": { "type": "object", "properties": { "resource": { "type": "string", "description": "The type of the Forage resource involved in the error." }, "ref": { "type": "string", "description": "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": { "type": "object", "description": "Additional details about the error, if applicable." } } }, "example": [] }, "ErrorResponseObject": { "type": "object", "description": "An object that includes details about the error.", "properties": { "path": { "type": "string", "description": "The requested endpoint." }, "errors": { "$ref": "#/components/schemas/ErrorsArray" } } }, "BalanceSessionRequest": { "type": "object", "description": "This object starts a Custom Balance Check Forage `Session`, used to check the balance of an already-stored Forage `PaymentMethod`.\n", "properties": { "payment_method": { "type": "string", "description": "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.\n\nSend a `POST` to [`/payment_methods/`](https://docs.joinforage.app/reference/create-payment-method) to create a `PaymentMethod`.\n" }, "success_redirect_url": { "type": "string", "description": "The URL that Forage redirects your customer to if the balance inquiry is successful." }, "cancel_redirect_url": { "type": "string", "description": "The URL that Forage redirects your customer to if the balance inquiry is canceled." } }, "required": [ "payment_method", "success_redirect_url", "cancel_redirect_url" ] }, "BalanceSessionResponse": { "allOf": [ { "$ref": "#/components/schemas/BalanceSessionRequest" }, { "type": "object", "properties": { "ref": { "type": "string", "description": "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": { "type": "string", "format": "url", "description": "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.", "example": "https://checkout.joinforage.app/balance?session=93410bcaff&merchant=1234567" }, "previous_errors": { "$ref": "#/components/schemas/ErrorsArray" } } } ], "example": { "ref": "93410bcaff", "payment_method": "b16673fe21", "success_redirect_url": "https://www.your-app.com/?status=SUCCEEDED", "cancel_redirect_url": "https://www.your-app.com/?status=CANCELED", "redirect_url": "https://checkout.joinforage.app/balance?session=93410bcaff&merchant=1234567", "previous_errors": [] } } }, "responses": { "BalanceSession200": { "description": "__OK__ - Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceSessionResponse" } } } } }, "parameters": { "BearerTokenHeader": { "name": "Authorization", "in": "header", "description": "An OAuth 2.0 bearer token that validates the request. You can use either a short-lived [session token](https://docs.joinforage.app/docs/authentication#session-tokens) if the request is coming from the front-end, or an [authentication token](https://docs.joinforage.app/docs/authentication#authentication-tokens) for server-side requests. Pass the token in this header after the word `Bearer` and a whitespace, for example `Bearer `.", "schema": { "type": "string" }, "required": true }, "MerchantAccountHeader": { "name": "Merchant-Account", "in": "header", "description": "A unique merchant ID that Forage provides during onboarding, as in `123ab45c67`. The Merchant ID can be found in the Forage [sandbox](https://dashboard.sandbox.joinforage.app/login/) or [production](https://dashboard.joinforage.app/login/) dashboard.", "schema": { "type": "string" }, "required": true } }, "securitySchemes": { "OAuth2": { "type": "oauth2", "description": "Pass the access token in the 'Authorization' header with the format \"Bearer ${token}\", i.e. the word \"Bearer\" and your access token from the /o/token/ API, separated by whitespace.\n", "flows": { "password": { "tokenUrl": "/o/token/", "scopes": { "hosted_checkout": "Scope for tokens used by merchant applications which allow Forage to manage split tender processing (i.e. EBT + Credit/Debit).\n", "pinpad_only": "Scope for tokens used by merchant applications which manage their own split tender (i.e. Forage Checkout is used only for EBT processing).\n" } }, "clientCredentials": { "tokenUrl": "/o/token/", "scopes": { "internal": "Scope for tokens used by Forage internal applications.\n", "pin-protected": "Scope for tokens which can access secure storage.\n", "disbursement": "Scope for tokens which can disburse money to merchants.\n" } } } } } } } ``` # Sibling pages * [Create a Custom Balance Check Session](https://docs.joinforage.app/reference/create-custom-balance-check-session.md) * [Create a Custom Payment Capture Session](https://docs.joinforage.app/reference/create-capture-session.md)