Create a Custom Payment Capture Session

post

https://{environment}.joinforage.app/api/capture_sessions/

A POST request to /capture_sessions/ initiates a Session of the Forage Custom Payment Capture UI.

The response payload represents the Custom Payment Capture 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 Create an Order Payment, or to check the status of the Order via a GET to /orders/{order_ref}/
redirect_url is the URL that launches the front-end, customer-facing Forage UI
- Point customers to this URL to enter their PIN to complete checkout

If PIN entry is successful, then Forage points the customer to the success_redirect_url specified in the request body. Forage directs the customer to the cancel_redirect_url if they cancel the balance inquiry from the Forage UI.

To check the status of an Order after the customer completes the Forage UI, send a GET to /orders/{order_ref}/.

📘
Use customer_id For Better Performance
Pass customer_id in the request to Create a Capture Session.
Forage automatically adds the customer_id to the Session's corresponding Order and OrderPayments.
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 the request to create the Session 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 Capture 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.

Body Params

Pass the following fields in the body of the request to /capture_sessions/ to initiate a Custom Capture Session.

This object starts a Forage Session, an instance of the ready-to-use Forage Checkout UI. It either initiates a Custom Capture Session, if passed as is to the /capture_sessions/ endpoint, or a Fully Hosted Session, if passed to the /sessions/ endpoint. Refer to each endpoint's documentation for details.

success_redirect_url

string

required

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

cancel_redirect_url

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.

is_delivery

boolean

Whether the order is for delivery or pickup. Optional — defaults to false. Forage reports this value to FNS for regulatory purposes.

is_commercial_shipping

boolean | null

Whether the order is to be shipped commercially. FNS uses this value in its database for statistics.

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

platform_fee

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.

customer_id

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.

external_order_id

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.

external_location_id

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.

payment_details

object

required

A 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. Only use this field if you have a pre-existing PaymentMethod ref that should be used in this session.

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

Headers

Merchant-Account

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.

Idempotency-Key

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.

API-Version

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

200OK - Success

400Bad request - The request was not accepted because of an error in the request body or path.

401Unauthorized

409Conflict

423Locked - The request could not be completed because the target resource is currently locked.

429Too Many Requests

500Internal Server Error