✅
Forage Sessions are only relevant to Fully Hosted and Custom integrations.
If you’re building with one of the Forage SDKs, then refer to the Payments API resources for SDKs.

A Forage Session represents an instance of the ready-to-use Forage Checkout UI. To create a Session, send a POST to the corresponding Payments API endpoint:

/sessions/creates a Fully Hosted Session
/balance_sessions/ creates a Custom Balance Check Session
/capture_sessions/ creates a Custom Capture Session

The exact payload of the Session response object varies by endpoint. However, every Session includes a redirect_url property that links to the Forage UI. When a customer is ready to pay with EBT or check their EBT Card balance, direct them to this URL.

Fully Hosted `Session`

📘
Learn more about Fully Hosted integrations.

A Fully Hosted Session object includes a redirect_url to a Forage Checkout UI that a customer can use to checkout with both their EBT Card and additional payment methods. Under the hood, a Fully Hosted Session creates a Forage Order to represent the transaction.

A successful POST to /sessions/ returns a Session object with the following shape:

{
  "ref": "b873fe62dc",
  "snap_total": "0.00",
  "ebt_cash_total": "20.00",
  "remaining_total": "0.00",
  "product_list": [
    {
      "name": "Take and Bake Lasagna",
      "upc": "860",
      "unit_price": "20.00",
      "quantity": 1,
      "tax_rate": "0.000000",
      "taxes_charged": null,
      "taxes_exempted": null,
      "eligibility": "ebt_cash"
    }
  ],
  "status": "draft",
  "delivery_address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "1856 Market St.",
    "line2": null,
    "state": "CA",
    "zipcode": "94102"
  },
  "is_delivery": true,
  "success_redirect_url": "https://www.joinforage.com/?status=SUCCEEDED",
  "cancel_redirect_url": "https://www.joinforage.com/?status=CANCELED",
  "supported_benefits": [
    "snap",
    "ebt_cash",
    "non_ebt"
  ],
  "success_date": null,
  "receipt": null,
  "customer_id": null,
  "is_commercial_shipping": null,
  "redirect_url": "https://checkout.sandbox.joinforage.app/payment?order=b873fe62dc&merchant=9000055"
}

Properties

✅
A Custom Payment Capture Session also includes the below properties.
Note the * that indicates if a property is excluded from a Custom Payment Capture Session.

Property	Type	Description
`ref`	string	A unique reference hash for the Forage `Order` created for this Session.
`snap_total`	string	The SNAP eligible portion of the order total in USD. Precision to the penny is supported.
`ebt_cash_total`	string	The EBT Cash eligible portion of the order total in USD. Precision to the penny is supported.
`remaining_total`* *Not included in Custom Payment Capture `Session` objects	string	The portion of the Order total in USD that is not SNAP or EBT Cash eligible. This amount must be charged to a credit or debit card. Precision to the penny is supported.
`product_list`* *Not included in Custom Payment Capture `Session` objects	array of objects	A list of the products in the customer’s cart. If there are no taxes applied to any of the products, then this field can be empty. Refer to `product_list`for item object details.
`status`	string	The status of the customer’s `Order`. One of: - `canceled` - `draft` (the status at the start, when a Session is created) - `failed` - `processing` - `succeeded`
`delivery_address`	object	The address for delivery or pickup of the order. Refer to `delivery_address` for details.
`is_delivery`	boolean	Whether the order is for delivery or pickup.
`success_redirect_url`	string	The URL to redirect your customer to if the Order is completed successfully.
`cancel_redirect_url`	string	The URL to redirect your customer to if they cancel the order.
`supported_benefits`	array of strings	The set of benefits that can be applied at checkout, including any or all of the values in: `["snap", "ebt_cash", "non_ebt"]`
`success_date`	ISO 8601 date-time string	The date when the `Order` was successfully charged.
`receipt`	object	The information that you are required to display to the EBT cardholder after order/refund completion, according to FNS regulations. This field is null if receipt data is not yet available for the Order. Refer to `receipt` for details.
`customer_id`	string	A unique ID for the end customer making the payment.
`is_commercial_shipping`	boolean	Whether the order is to be shipped commercially. FNS uses this value in its database for statistics.
`redirect_url`	string	The URL that launches a Forage Fully Hosted Session. Point a customer to this URL when they are ready to complete checkout

product_list

Every object in a product_list that represents an item in a customer’s cart includes the following fields:

Property	Type	Description
`name`	string	The name of the item.
`upc`	string	The item’s Universal Product Code.
`unit_price`	string	The cost of a single item.
`quantity`	number	The number of the items in the customer’s cart.
`tax_rate`	number	The tax rate for the item, represented as a decimal with at most six decimal places. A value of 0 indicates a tax rate of 0%, and a value of 1 indicates a tax rate of 100%. To set a 2% tax rate, for example, set the value to 0.02. Use this field if the product is subject to only one tax rate. If multiple tax rates apply, for example both a state grocery tax and a sweetened beverage tax, then use the `tax_rate_list` param instead of `tax_rate`.
`taxes_charged`	number	The taxes charged to the customer in USD. Precision to the penny is supported.
`taxes_exempted`	number	The total amount of taxes that the `Order` is exempt from. Precision to the penny is supported.
`eligibility`	string	The EBT benefits, if any, that can be used to pay for the item. One of: - `snap` - `ebt_cash` - `non_ebt`

tax_rate_list

If multiple tax rates apply to an item in a product_list, then instead of tax_rate pass a tax_rate_list array of objects that details the following fields for every relevant tax:

Property	Type	Description
`imposed_by`	string	The name of the entity applying the tax.
`tax_rate`	number	The tax rate for the product, represented as a decimal with at most six decimal places. A value of 0 indicates a tax rate of 0%, and a value of 1 indicates a tax rate of 100%. If only one tax rate applies, then use the single `tax_rate` param at the `product_list` level instead.

delivery_address

Property	Type	Description
`city`	string	The name of the city.
`country`	string	The constant string US.
`line1`	string	The first line of the street address.
`line2`	string	The second line of the street address.
`state`	string	A two-letter abbreviation for the US state.
`zipcode`	string	A zip or postal code.

receipt

Property	Type	Description
`ref_number`	string	The reference hash of the Payment object, a one-time charge to a previously created Forage PaymentMethod.
`snap_amount`	string	The amount charged/refunded to the SNAP balance of the EBT card, if any, represented as a numeric string.
`ebt_cash_amount`	string	The amount charged/refunded to the Cash balance of the EBT Card, if any, represented as a numeric string.
`balance`	object	The available SNAP and Cash balances on the EBT account associated with the EBT Card. Refer to `balance`for details.
`last_4`	string	The last four digits of the EBT Card.
`message`	string	A message from the EBT payment network that must be displayed to the EBT cardholder.
`transaction_type`	string	A constant string that is used to identify the transaction associated with this receipt data. One of: order, refund.
`created`	ISO 8601 date-time string	The date-time when the payment was created.

balance

Property	Type	Description
`snap`	string	The available SNAP balance on the customer’s EBT Card, represented as a numeric string.
`non_snap`	string	The available EBT Cash balance left on the EBT Card, represented as a numeric string.
`updated`	ISO 8601 date-time string	The date-time when the funds in the account last changed.

Example request

Create a Fully Hosted `Session`

curl --request POST \
     --url https://api.sandbox.joinforage.app/api/sessions/ \
     --header 'Authorization: Bearer <authentication-token>' \
     --header 'Idempotency-Key: <idempotency-key>' \
     --header 'Merchant-Account: <merchant-id>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "delivery_address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "1856 Market St.",
    "line2": "Unit 3",
    "zipcode": "94102",
    "state": "CA"
  },
  "is_delivery": true,
  "snap_total": 25.99,
  "ebt_cash_total": 25.99,
  "success_redirect_url": "<https://your-app.com/receipt>",
  "cancel_redirect_url": "<https://your-app.com/order-canceled>",
  "remaining_total": 5.99
}
'

📘
Refer to the /sessions/ endpoint documentation for complete details.

Custom Balance Check `Session`

📘
Learn more about Custom integrations.

A Custom Balance Check Session object includes a redirect_url to a Forage UI that a customer can use to check the balance of their EBT Card.

A successful POST to /balance_sessions/ returns a Session object with a shape like the following:

{
    "ref": "593ee1501a",
    "payment_method": "6592770450",
    "success_redirect_url": "<https://your-app.com/receipt>",
    "cancel_redirect_url": "<https://your-app.com/order-canceled>",
    "redirect_url": "https://checkout.sandbox.joinforage.app/balance?session=593ee1501a&merchant=9000055"
}

Properties

Property	Type	Description
`ref`	string	A unique identifier for the Session.
`payment_method`	string	The unique ref for the Forage PaymentMethod instance.
`success_redirect_url`	string	The URL to redirect your customer to after a successful balance check.
`cancel_redirect_url`	string	The URL to redirect your customer to if they cancel the balance inquiry.
`redirect_url`	string	The URL that launches a Forage Custom Balance Check Session. Point a customer to this URL when they are ready to perform a balance inquiry.

Example requests

Create a Custom Balance Check `Session`

curl --request POST \
     --url https://api.sandbox.joinforage.app/api/balance_sessions/ \
     --header 'Authorization: Bearer <authentication-token>' \
     --header 'Idempotency-Key: <idempotency-key>' \
     --header 'Merchant-Account: <merchant-id>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "payment_method": "05e5349f0a",
  "success_redirect_url": "<https://your-app.com/receipt>",
  "cancel_redirect_url": "<https://your-app.com/balance-check-canceled>"
}
'

Retrieve a Custom Balance Check `Session`

curl --request GET \
     --url https://api.sandbox.joinforage.app/api/balance_sessions/session_ref/ \
     --header 'Authorization: Bearer <authentication-token>' \
     --header 'Merchant-Account: <merchant-id>' \
     --header 'accept: application/json'

📘
Refer to the /balance_sessions/ endpoint documentation for complete details.

Custom Payment Capture `Session`

📘
Learn more about Custom integrations.

A Custom Payment Capture Session object includes a redirect_url to a Forage Checkout UI that a customer can use to pay for an order with their EBT Card. Credit card and other payment types need to be handled independently of Forage.

A successful POST to /capture_sessions/ returns a Session object that is almost identical to the Fully Hosted Session object. Please refer to that section for details, and note the * that marks if a field is excluded from the response for a Custom Payment Capture Session.

Example request

Create a Custom Payment Capture `Session`

curl --request POST \
     --url https://api.sandbox.joinforage.app/api/capture_sessions/ \
     --header 'Authorization: Bearer <authentication-token>' \
     --header 'Idempotency-Key: <idempotency-key>' \
     --header 'Merchant-Account: <merchant-id>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "delivery_address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "1856 Market St.",
    "line2": "Unit 3",
    "zipcode": "94102",
    "state": "CA"
  },
  "is_delivery": true,
  "snap_total": 25.99,
  "ebt_cash_total": 25.99,
  "success_redirect_url": "<https://your-app.com/receipt>",
  "cancel_redirect_url": "<https://your-app.com/order-canceled>",
  "customer_id": "123123123123"
}
'

📘
Refer to the /capture_sessions/ endpoint documentation for complete details.

Fully Hosted Session

Properties

product_list

tax_rate_list

delivery_address

receipt

balance

Example request

Create a Fully Hosted Session

Custom Balance Check Session

Properties

Example requests

Create a Custom Balance Check Session

Retrieve a Custom Balance Check Session

Custom Payment Capture Session

Example request

Create a Custom Payment Capture Session

Fully Hosted `Session`

Create a Fully Hosted `Session`

Custom Balance Check `Session`

Create a Custom Balance Check `Session`

Retrieve a Custom Balance Check `Session`

Custom Payment Capture `Session`

Create a Custom Payment Capture `Session`