Create a Fully Hosted Session

✅

This endpoint is only relevant to Fully Hosted integrations.

For more information about Fully Hosted, check out the Forage guide.

A POST request to /sessions/ initiates a Session of the Fully Hosted Forage Checkout UI. On success, the API creates a Forage Order.

The response payload represents the Fully Hosted Session. The ref and redirect_url fields are the most important:

• ref represents the Order
  • Store this ref so that you can pass it in a future request to Retrieve the Order outcome
• redirect_url is the URL that launches the customer-facing Forage Checkout UI
  • Point customers to this URL when they’re ready to complete checkout

Important Fully Hosted Session parameters

How to use snap_total and ebt_cash_total

Keep snap_total to SNAP eligible items only, and ebt_cash_total to EBT Cash eligible items only.

Pass the tax_rate of every item in the product_list so that Forage can handle taxes

Forage calculates the taxes for the Order depending on how the customer decides to pay. SNAP eligible items are only subject to taxes when purchased with a credit/debit card, per FNS regulations. Retrieve the Order outcome and inspect the sales_tax_applied response value to find the final tax amount charged to the customer, or review the taxes_charged on a per item level in the product_list field.

Pass customer_id to speed up the request

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 could take longer to process. It is strongly recommended to pass customer_id.

Each customer should only have one unique customer_id. For example, if you create both a Forage Session and a PaymentMethod for the same customer, then the customer_id should be the same in both requests.

📘

Guides

• How Forage Fully Hosted integrations work
• Fully Hosted Quickstart
• Fully Hosted Session payload