📘
Forage Session Objects
Forage Session objects are only relevant to Fully Hosted and Custom integrations.

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 Payment 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`

For more information, see our Fully Hosted Integrations guide.

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.your-app.com/?status=SUCCEEDED",
  "cancel_redirect_url": "https://www.your-app.com/?status=CANCELED",
  "supported_benefits": [
    "snap",
    "ebt_cash",
    "non_ebt"
  ],
  "success_date": null,
  "receipt": null,
  "customer_id": "abc123",
  "is_commercial_shipping": null,
  "redirect_url": "https://checkout.sandbox.joinforage.app/payment?order=b873fe62dc&merchant=9000055",
  "previous_errors": []
}

Properties

Property	Type	Description
`ref`	string	A unique reference hash for the Forage `Order` created for this Session.
`snap_total`	number	The SNAP eligible portion of the order cost in USD. Precision to the penny is supported.
`ebt_cash_total`	number	The EBT Cash eligible portion of the order cost in USD. Precision to the penny is supported.
`remaining_total`	number	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`	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. This information is required per FNS regulations. Defaults to `false` if not provided.
`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	A UTC-8 timestamp of 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. This field helps Forage's servers more quickly identify the customer associated with the request. While `customer_id` is not technically required, if you omit it then requests could take longer to process. If you're providing your internal customer ID, then we recommend that you hash the value before sending it on the payload. Each customer should only have one unique `customer_id`. For example, if you create both a `PaymentMethod` and a Forage Session for the same customer, then the `customer_id` should be the same in both requests.
`is_commercial_shipping`	boolean	Whether the order is to be shipped commercially. FNS uses this value in its database for statistics.
`platform_fee`	number	An optional field, for use by a platform supporting multiple merchants, that indicates the percentage cut of each payment that the platform charges as a fee.
`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.
`previous_errors`	array	An array of objects that detail information about any errors triggered by the request. If the request was successful and without errors, then the field is returned as an empty array. Refer to `previous_errors` for details.

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 in the product_list instead of tax_rate pass tax_rate_list, including the following fields:

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.

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

⚠️
When receipt Becomes Available
The receipt value is null when a Session is first created and until receipt data is available. Pass the ref returned in the response to create the Session in periodic GET requests to/orders/{order_ref}/ until the status of the Order associated with the Session is succeeded. At that point, the receipt data, including the balance, is up-to-date.

Property	Type	Description
`ref_number`	string	The reference hash of the `Order`.
`is_voided`	boolean	Whether the transaction associated with this receipt has been voided. If `false`, then the transaction finished processing as expected. If `true`, then the transaction was reversed.
`snap_amount`	string	The amount charged/refunded to the SNAP balance of the EBT Card, represented as a numeric string.
`ebt_cash_amount`	string	The amount charged/refunded to the EBT Cash balance of the EBT Card, represented as a numeric string.
`other_amount`	string	The amount charged or refunded to any payment method that is not an EBT Card, represented as a numeric string.
`sales_tax_applied`	string	The USD amount of taxes charged to the customer’s non-EBT payment instrument, represented as a numeric string.
`balance`	object	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 the receipt. For Forage Sessions, the value is always `Order`.
`created`	ISO 8601 date-time string	A UTC-8 timestamp of when the `Session` 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	A UTC-8 date-time timestamp of when the funds in the account last changed.

previous_errors

Each object in the previous_errors array includes the following fields:

Property	Type	Description
`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	An object that details the specific source of the Forage error, including two keys: - `resource`: The type of the Forage resource involved in the error. - `ref`: 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.

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,
  "customer_id": "abc123",
  "success_redirect_url": "https://your-app.com/receipt",
  "cancel_redirect_url": "https://your-app.com/order-canceled",
  "remaining_total": 5.99
}
'

📘
Pass customer_id In The Request Body
customer_id helps Forage's servers more quickly identify and associate the correct customer with the Session. While customer_id is not technically a required parameter, if you omit it then requests to create the Session could take longer to process.
Each customer should only have one unique customer_id. For example, if you create both a PaymentMethod and a Forage Session for the same customer, then the customer_id should be the same in both requests.

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",
    "previous_errors": []
}

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.
`previous_errors`	array	An array of objects that detail information about any errors triggered by the request. If the request was successful and without errors, then the field is returned as an empty array. Refer to `previous_errors` for details.

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 with the following shape:

{
  "status": "draft",
  "delivery_address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "1857 Market St.",
    "state": "CA",
    "zipcode": "94117"
  },
  "is_delivery": false,
  "payment_details": {
    "snap_payment": {
      "ref": "b29dj92e4g",
      "amount": 20.12,
      "metadata": {},
      "payment_method": "fsdf45345",
      "description": "A SNAP payment",
      "funding_type": "ebt_snap"
    },
    "ebt_cash_payment": {
      "ref": "c4gdj92e4g",
      "amount": 25.99,
      "metadata": {},
      "payment_method": "fsdf45345",
      "description": "An EBT Cash payment",
      "funding_type": "ebt_cash"
    }
  },
  "supported_benefits": [
    "snap",
    "ebt_cash"
  ],
  "ref": "b873fe62dc",
  "success_date": null,
  "receipt": null,
  "customer_id": "abc123",
  "is_commercial_shipping": null,
  "success_redirect_url": "https://www.your-app.com/?status=SUCCEEDED",
  "cancel_redirect_url": "https://www.your-app.com/?status=CANCELED",
  "redirect_url": "https://checkout.sandbox.joinforage.app/payment?order=b873fe62dc&merchant=9000055",
  "previous_errors": []
}

Properties

Property	Type	Description
`status`	string	A unique reference hash for the Forage `Order` created for this Session.
`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. This information is required per FNS regulations. Defaults to `false` if not provided.
`payment_details`	object	A list of `snap_payment` and/or `ebt_cash_payment` object(s) that Forage uses to create `OrderPayments`. In the response, Forage adds a unique `ref` identifier to every payment in the list. You must build with Forage Version `2024-03-05` to pass `payment_details`. Either set `2024-03-05` as the API-Version header on a per request basis, or set the version for all requests in the Forage dashboard.
`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"]`
`ref`	string	A unique reference hash for the Forage `Order` created for this Session.
`success_date`	string	A UTC-8 timestamp of 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. This field helps Forage's servers more quickly identify the customer associated with the request. While `customer_id` is not technically required, if you omit it then requests could take longer to process. If you're providing your internal customer ID, then we recommend that you hash the value before sending it on the payload. Each customer should only have one unique `customer_id`. For example, if you create both a `PaymentMethod` and a Forage Session for the same customer, then the `customer_id` should be the same in both requests.
`is_commercial_shipping`	boolean	Whether the order is to be shipped commercially. FNS uses this value in its database for statistics.
`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.
`redirect_url`	string	The URL that launches a Payment Capture Session. Point a customer to this URL when they are ready to complete checkout.
`previous_errors`	array	An array of objects that detail information about any errors triggered by the request. If the request was successful and without errors, then the field is returned as an empty array. Refer to `previous_errors` for details.

`payment_details`

Each snap_payment or ebt_cash_payment object contains the following fields:

Property	Type	Description
`amount`	number	A positive decimal number that represents how much to charge the `PaymentMethod` in USD. Precision to the penny is supported. To charge multiple balances, add both a `snap_payment` and `ebt_cash_payment` object to the `payment_details` list. The minimum amount that can be charged is `0.01`.
`metadata`	object	A set of optional, merchant-defined key-value pairs that can be added to an object. For example, some merchants attach their credit card processor’s ID for the customer making the payment. If there’s no additional information that you’d like to add, then pass an empty object as the value.
`payment_method`	string	The unique reference hash for the existing Forage `PaymentMethod` that is to be charged in this transaction.
`description`	string	A string that describes the payment.
`funding_type`	string	A string that represents the type of tender. Use `ebt_cash` for `ebt_cash_payment` and `ebt_snap` for `snap_payment`.

Example request

Create a Custom Payment Capture Session

curl --request POST \
     --url https://api.sandbox.joinforage.app/api/capture_sessions/ \
     --header 'API-Version: 2024-03-05'
     --header 'Authorization: Bearer <authentication_token>' \
     --header 'Idempotency-Key: <idempotency-key>' \
     --header 'Merchant-Account: <merchant-account>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '

{
    "success_redirect_url" : "https://www.joinforage.com/status=SUCCEEDED",
    "cancel_redirect_url" : "https://www.joinforage.com/status=CANCELED",
    "delivery_address": {
        "city": "San Francisco",
        "country": "US",
        "line1": "1857 Market St.",
        "state": "CA",
        "zipcode": "94117"
    },
    "is_delivery" : false,
    "supported_benefits": ["snap", "ebt_cash"],
    "customer_id": "abc123",
    "payment_details": {
        "snap_payment": {
           "amount": 20.12,
           "metadata": {},
           "payment_method": "fsdf45345"
           "description": "A SNAP payment",
           "funding_type": "ebt_snap"
        },
        "ebt_cash_payment": {
            "amount": 25.99,
            "metadata": {},
            "payment_method": "fsdf45345"
            "description": "An EBT Cash payment",
            "funding_type": "ebt_cash"
         }
    }
}

📘
Pass customer_id In The Request Body
customer_id helps Forage's servers more quickly identify and associate the correct customer with the Session. While customer_id is not technically a required parameter, if you omit it then requests to create the Session could take longer to process.
Each customer should only have one unique customer_id. For example, if you create both a PaymentMethod and a Forage Session for the same customer, then the customer_id should be the same in both requests.

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

Forage Sessions

📘
Forage `Session` Objects

Fully Hosted `Session`

Properties

product_list

tax_rate_list

delivery_address

receipt

⚠️
When `receipt` Becomes Available

balance

previous_errors

Example request

Create a Fully Hosted `Session`

📘
Pass `customer_id` In The Request Body

Custom Balance Check `Session`

Properties

Example requests

Create a Custom Balance Check `Session`

Retrieve a Custom Balance Check `Session`

Custom Payment Capture `Session`

Properties

`payment_details`

Example request

Create a Custom Payment Capture Session

📘
Pass `customer_id` In The Request Body

📘Forage Session Objects

Fully Hosted Session

Properties

product_list

tax_rate_list

delivery_address

receipt

⚠️When receipt Becomes Available

balance

previous_errors

Example request

Create a Fully Hosted Session

📘Pass customer_id In The Request Body

Custom Balance Check Session

Properties

Example requests

Create a Custom Balance Check Session

Retrieve a Custom Balance Check Session

Custom Payment Capture Session

Properties

payment_details

Example request

Create a Custom Payment Capture Session

📘Pass customer_id In The Request Body

📘
Forage `Session` Objects

Fully Hosted `Session`

⚠️
When `receipt` Becomes Available

Create a Fully Hosted `Session`

📘
Pass `customer_id` In The Request Body

Custom Balance Check `Session`

Create a Custom Balance Check `Session`

Retrieve a Custom Balance Check `Session`

Custom Payment Capture `Session`

`payment_details`

📘
Pass `customer_id` In The Request Body