Create a Custom Balance Check Session

post

https://{environment}.joinforage.app/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 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. 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}/ and inspect the balance field of the response to retrieve their EBT Card balance.

See these guide for additional information:

Body Params

Pass the following fields in the body of the request to /balance_sessions/ to start a Custom Balance Check Session.

payment_method

string

required

The unique, hashed reference ID to the Forage PaymentMethod 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/ 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.

Headers

Authorization

string

required

An OAuth 2.0 bearer token that validates the request. You can use either a short-lived session token if the request is coming from the front-end, or an authentication token for server-side requests. Pass the token in this header after the word Bearer and a whitespace, for example Bearer <api_key>.

Merchant-Account

string

required

A unique merchant ID that Forage provides during onboarding, as in 123ab45c67. The Merchant ID can be found in the Forage sandbox or production dashboard.

Idempotency-Key

string

required

An alphanumeric key that clients can use to identify repeated requests that are dropped in transit. Generate a distinct key for every unique request and only re-use keys for retries.

Responses

200OK - Success

400Bad request - The request was not accepted because of an error in the request body or path.

401Unauthorized

409Conflict

423Locked - The request could not be completed because the target resource is currently locked.

429Too Many Requests

500Internal Server Error