Sign in

v1

latestOpenAPI 3.0.02026-07-244352379.2 KB
Custom Sessions

Create a Custom Payment Capture Session

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

post/api/capture_sessions/

Request body

success_redirect_urlstring required

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

cancel_redirect_urlstring required

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

is_deliveryboolean

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

is_commercial_shippingboolean nullable

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

supported_benefitsstring[]

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

platform_feenumber

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_idstring

⚠️ 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_idstring

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_idstring

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.

Example request

{
  "delivery_address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "1856 Market St.",
    "state": "CA",
    "zipcode": "94102"
  },
  "is_delivery": false,
  "payment_details": {
    "snap_payment": {
      "amount": 20.12,
      "metadata": {},
      "payment_method": "fsdf45345",
      "description": "A SNAP payment"
    },
    "ebt_cash_payment": {
      "amount": 25.99,
      "metadata": {},
      "payment_method": "fsdf45345",
      "description": "An EBT Cash payment"
    }
  },
  "customer_id": "cus_1234567890",
  "supported_benefits": [
    "snap",
    "non_ebt"
  ],
  "success_redirect_url": "https://www.your-app.com/?status=SUCCEEDED",
  "cancel_redirect_url": "https://www.your-app.com/?status=CANCELED"
}

Response

OK - Success

refstring

A unique reference hash for the Order created for this Session.

status'draft' | 'processing' | 'failed' | 'succeeded' | 'canceled'

The status is always draft at the start.

success_datestring date-time

A UTC timestamp that indicates when all of the Payments associated with the Order are successfully charged, represented as an ISO 8601 date-time string.

expires_atstring

A UTC timestamp of when the Order associated with the Payment Capture Session will expire if it is not captured or canceled, set to 30 minutes from when the Order is created.

is_commercial_shippingboolean nullable

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

redirect_urlstring url

The URL that launches the Forage Session UI. Point a customer to this URL when they are ready to complete checkout.

success_redirect_urlstring required

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

cancel_redirect_urlstring required

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

is_deliveryboolean

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

supported_benefitsstring[]

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

platform_feenumber

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_idstring

⚠️ 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_idstring

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_idstring

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.

Example response

{
  "status": "draft",
  "delivery_address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "1856 Market St.",
    "state": "CA",
    "zipcode": "94102"
  },
  "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",
    "non_ebt"
  ],
  "ref": "b873fe62dc",
  "success_date": null,
  "receipt": null,
  "customer_id": null,
  "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": []
}