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 HostedSession
/balance_sessions/
creates a Custom Balance CheckSession
/capture_sessions/
creates a Custom CaptureSession
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
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 CaptureSession
.
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
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
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
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
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
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
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.