HomeGuidesReference↗ Forage Dashboard
Log In
Reference

Create a Fully Hosted Session

post
https://{environment}.joinforage.app/api/sessions/

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 Session UI
    • Point customers to this URL when they're ready to complete checkout

Important Fully Hosted Session parameters

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 and prefill stored payment methods

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.

When the same customer_id is provided for a returning customer, Forage will retrieve and reuse their stored payment method, if available. Alternatively, passing the same ebt_payment_method can also pre-fill the stored payment method in the checkout session.

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 to ensure continuity of stored payment methods.

See these guides for additional information:

Body Params

Pass the following fields in the body of the request to /sessions/ to start a Fully Hosted Session.

string
required

The URL that Forage should redirect your customer to if the Order is completed successfully.

string
required

The URL that Forage should redirect your customer to if the Order is cancelled.

delivery_address
object
required

⚠️ Exception: If the purchase is made in-store via a POS Terminal, then a delivery_address is not required when creating a Payment.

The address for delivery or pickup of the Order. Per FNS regulations, this value must always be provided. If the Order is for pickup, then use the merchant address.

boolean
required

Whether the order is for delivery or pickup. This information is required per FNS regulations. Defaults to false if not provided.

supported_benefits
array of strings

A list that limits the types of payment methods that can be applied at checkout, including any or all of the values in: ["snap", "ebt_cash", "non_ebt"]. Use supported_benefits only if you want to restrict the possible payment method types. Omit this field in all other cases. For example, pass ["snap", "non_ebt"] if you want to accept SNAP and credit card payments only (excluding EBT Cash).

supported_benefits
number

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

string
length ≤ 64

⚠️ If you’re integrating Forage with a POS Terminal, then do not use this param. It is only supported for online transactions.

A unique identifier for the end customer making the payment.

Forage automatically adds the customer_id to the Session's corresponding Order and OrderPayments.

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

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 (Fully Hosted or Custom) or Payment (SDK) for the same customer, then the customer_id should be the same in both requests to ensure continuity of stored payment methods.

string
length ≤ 64

A unique identifier for the order as created by the merchant or platform (not Forage).

When a merchant or platform passes this order ID to Forage, it persists in each Forage transaction related to the Order. This field enables merchants to map order IDs in their system to corresponding Forage Order IDs.

You must build with Forage Version 2023-05-15 or later to use external_order_id. Either pass 2023-05-15 as the API-Version header on a per request basis, or set the version for all requests in the Forage dashboard.

string

A unique identifier, provided by the merchant or platform (not Forage), that indicates the physical fulfillment location for the order. For example, this field could specify which location of a grocery store chain fulfilled an order.

product_list
array of objects
required

A list of products in the customer's cart at checkout.

Required Fields

Each item must include the following required fields:

  • name
  • upc
  • unit_price
  • quantity
  • eligibility

If there are no taxes applied to any of the products, then you can pass an empty array as the value.

This field is returned as null in the case of a Custom Session.

product_list*
string

The third-party payment processor's unique identifier for the customer. An optional field passed in anticipation of a customer applying a credit/debit card to an Order balance.

This field is returned as null in the case of a Custom Session.

You must build with Forage Version 2023-05-15 or later to use psp_customer_id. Either pass 2023-05-15 as the API-Version header on a per request basis, or set the version for all requests in the Forage dashboard.

string

A unique reference hash for an existing Forage PaymentMethod. Use this param if you'd like to pre-populate the payment method field in the checkout UI for a returning customer.

This field is only returned in the response if it is passed in the original request body.

Headers
string
required

An OAuth 2.0 authentication token that validates the request. Send a POST to the /o/token/ endpoint to generate an authentication token. Pass the token in this header after the word Bearer and a whitespace, for example Bearer <api_key>.

string
required

A unique merchant ID that Forage provides during onboarding, as in 123ab45c67. The Merchant ID can be found in the Forage sandbox or production dashboard.

string
required

An alphanumeric key that clients can use to identify repeated requests that are dropped in transit. Generate a distinct key for every unique request and only re-use keys for retries.

string

The Forage version, represented as a string with the format of a YYYY-MM-DD date.

If not specified in the request header, then the version defaults to the value set in the Forage dashboard.

Responses

Updated 16 days ago

Language
Credentials
OAuth2
URL
LoadingLoading…
Response
Choose an example:
application/json

Updated 16 days ago