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:

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.

PropertyTypeDescription
refstringA unique reference hash for the Forage Order created for this Session.
snap_totalstringThe SNAP eligible portion of the order total in USD. Precision to the penny is supported.
ebt_cash_totalstringThe 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
stringThe 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 objectsA 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_listfor item object details.
statusstringThe status of the customer’s Order. One of:

- canceled
- draft (the status at the start, when a Session is created)
- failed
- processing
- succeeded
delivery_addressobjectThe address for delivery or pickup of the order. Refer to delivery_address for details.
is_deliverybooleanWhether the order is for delivery or pickup.
success_redirect_urlstringThe URL to redirect your customer to if the Order is completed successfully.
cancel_redirect_urlstringThe URL to redirect your customer to if they cancel the order.
supported_benefitsarray of stringsThe set of benefits that can be applied at checkout, including any or all of the values in:

["snap", "ebt_cash", "non_ebt"]
success_dateISO 8601 date-time stringThe date when the Order was successfully charged.
receiptobjectThe 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_idstringA unique ID for the end customer making the payment.
is_commercial_shippingbooleanWhether the order is to be shipped commercially. FNS uses this value in its database for statistics.
redirect_urlstringThe 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:

PropertyTypeDescription
namestringThe name of the item.
upcstringThe item’s Universal Product Code.
unit_pricestringThe cost of a single item.
quantitynumberThe number of the items in the customer’s cart.
tax_ratenumberThe 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_chargednumberThe taxes charged to the customer in USD. Precision to the penny is supported.
taxes_exemptednumberThe total amount of taxes that the Order is exempt from. Precision to the penny is supported.
eligibilitystringThe 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:

PropertyTypeDescription
imposed_bystringThe name of the entity applying the tax.
tax_ratenumberThe 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

PropertyTypeDescription
citystringThe name of the city.
countrystringThe constant string US.
line1stringThe first line of the street address.
line2stringThe second line of the street address.
statestringA two-letter abbreviation for the US state.
zipcodestringA zip or postal code.

receipt

PropertyTypeDescription
ref_numberstringThe reference hash of the Payment object, a one-time charge to a previously created Forage PaymentMethod.
snap_amountstringThe amount charged/refunded to the SNAP balance of the EBT card, if any, represented as a numeric string.
ebt_cash_amountstringThe amount charged/refunded to the Cash balance of the EBT Card, if any, represented as a numeric string.
balanceobjectThe available SNAP and Cash balances on the EBT account associated with the EBT Card. Refer to balancefor details.
last_4stringThe last four digits of the EBT Card.
messagestringA message from the EBT payment network that must be displayed to the EBT cardholder.
transaction_typestringA constant string that is used to identify the transaction associated with this receipt data. One of: order, refund.
createdISO 8601 date-time stringThe date-time when the payment was created.

balance

PropertyTypeDescription
snapstringThe available SNAP balance on the customer’s EBT Card, represented as a numeric string.
non_snapstringThe available EBT Cash balance left on the EBT Card, represented as a numeric string.
updatedISO 8601 date-time stringThe 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

PropertyTypeDescription
refstringA unique identifier for the Session.
payment_methodstringThe unique ref for the Forage PaymentMethod instance.
success_redirect_urlstringThe URL to redirect your customer to after a successful balance check.
cancel_redirect_urlstringThe URL to redirect your customer to if they cancel the balance inquiry.
redirect_urlstringThe 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.