Forage Sessions

A Session object represents an instance of the ready-to-use Forage Checkout UI.

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:

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.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": 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_totalnumberThe SNAP eligible portion of the order cost in USD. Precision to the penny is supported.
ebt_cash_totalnumberThe EBT Cash eligible portion of the order cost in USD. Precision to the penny is supported.
remaining_total*

*Not included in Custom Payment Capture Session objects
numberThe 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. This information is required per FNS regulations. Defaults to false if not provided.
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.
platform_feenumberAn 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_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 in the product_list instead of tax_rate pass tax_rate_list, including the following fields:

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.

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

🚧

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.

PropertyTypeDescription
ref_numberstringThe reference hash of the Order.
is_voidedbooleanWhether 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_amountstringThe amount charged/refunded to the SNAP balance of the EBT Card, represented as a numeric string.
ebt_cash_amountstringThe amount charged/refunded to the EBT Cash balance of the EBT Card, represented as a numeric string.
other_amountstringThe amount charged or refunded to any payment method that is not an EBT Card, represented as a numeric string.
sales_tax_appliedstringThe USD amount of taxes charged to the customer’s non-EBT payment instrument, represented as a numeric string.
balanceobjectRefer 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 the receipt. For Forage Sessions, the value is always Order.
createdISO 8601 date-time stringA timestamp of when the Session 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.