HomeGuidesReference
Log In
Reference

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": "abc123",
  "is_commercial_shipping": null,
  "redirect_url": "https://checkout.sandbox.joinforage.app/payment?order=b873fe62dc&merchant=9000055",
  "previous_errors": []
}

Properties

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_totalnumberThe 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_listarray 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 stringA UTC-8 timestamp of 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.

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_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.
previous_errorsarrayAn 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:

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 UTC-8 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 stringA 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:

PropertyTypeDescription
codestringA short string that represents the error.
messagestringA developer-facing message with more details about the error, not to be displayed to customers.
sourceobjectAn 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.
detailsobjectAdditional 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

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.
previous_errorsarrayAn 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

PropertyTypeDescription
statusstringA unique reference hash for the Forage Order created for this Session.
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.
payment_detailsobjectA 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_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"]
refstringA unique reference hash for the Forage Order created for this Session.
success_datestringA UTC-8 timestamp of 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.

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_shippingbooleanWhether the order is to be shipped commercially. FNS uses this value in its database for statistics.
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.
redirect_urlstringThe URL that launches a Payment Capture Session. Point a customer to this URL when they are ready to complete checkout.
previous_errorsarrayAn 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:

PropertyTypeDescription
amountnumberA 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.
metadataobjectA 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_methodstringThe unique reference hash for the existing Forage PaymentMethod that is to be charged in this transaction.
descriptionstringA string that describes the payment.
funding_typestringA 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.