---
updatedAt: 2026-05-07T18:17:26.000Z
agentTools:
  projectIndex: https://docs.joinforage.app/llms.txt
---

# Create a Fully Hosted Session

A `POST` request to `/sessions/` initiates a `Session` of the Fully Hosted Forage Checkout UI. On success, the API creates a Forage [`Order`](ref:orders).

The response payload represents the [Fully Hosted `Session`](ref:forage-sessions#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](ref:create-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](ref:get-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:

- [How Forage Fully Hosted integrations work](doc:fully-hosted#how-it-works)
- [Fully Hosted Quickstart](doc:fully-hosted-quickstart)
- [Fully Hosted `Session` payload](ref:forage-sessions#fully-hosted-session)


# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "x-readme": {
    "explorer-enabled": false,
    "proxy-enabled": false
  },
  "info": {
    "title": "Forage Payments API",
    "description": "The Forage Payments API is a REST API for processing Electronic Benefits Transfer (EBT) payments (SNAP and EBT Cash) in your e-commerce or in-store application.\n\nProcessing any EBT payment, or checking an EBT card's balance, requires the cardholder's PIN. Federal regulations require all PIN entry to happen through a PCI-compliant, USDA-approved interface. Forage provides that interface, so EBT PIN collection always happens through a Forage-hosted surface (Forage Checkout or a Forage SDK), never directly in your own form. Some endpoints (for example, capture and balance) are only reachable through that surface because they require PIN data in the request.\n\nEBT rarely covers an entire order: items like delivery fees and non-eligible products can't be paid with SNAP or EBT Cash. You decide how to handle the remaining balance (split tender) and any credit or debit processing alongside the EBT portion.\n\nForage offers four integration options. Pick the one that fits your platform and engineering resources:\n\n1. **Fully Hosted Checkout.** Forage processes EBT and credit/debit through a Forage-hosted Checkout UI. Lowest engineering effort, and Forage absorbs most error handling. See the [Fully Hosted Checkout guide](https://docs.joinforage.app/docs/fully-hosted).\n2. **Custom Checkout.** Forage processes EBT; you handle split tender, taxes, and credit/debit in your own checkout flow. Best when you want minimal changes to your existing UX. See the [Custom Checkout guide](https://docs.joinforage.app/docs/custom).\n3. **Online SDKs.** Client-side SDKs for [web](https://docs.joinforage.app/docs/forage-js), [iOS](https://docs.joinforage.app/docs/ios), and [Android](https://docs.joinforage.app/docs/android) that collect EBT PINs in your app while keeping you out of PCI scope.\n4. **POS Terminal SDK.** Accept in-person EBT payments on an Android POS device. See the [POS Terminal guide](https://docs.joinforage.app/docs/forage-terminal-android).\n\nAs a general principle, any data created by your requests, or by your customers on a Forage-hosted surface, is retrievable through GET requests to the appropriate resource.\n\nHave more questions? Use our [contact form](https://www.joinforage.com/get-in-touch) to reach our sales and engineering support teams.\n",
    "contact": {
      "name": "API Support",
      "email": "engineering@joinforage.com"
    },
    "version": "2025-08-04"
  },
  "externalDocs": {
    "description": "Forage documentation",
    "url": "https://docs.joinforage.app/"
  },
  "servers": [
    {
      "url": "https://{environment}.joinforage.app",
      "variables": {
        "environment": {
          "default": "api.sandbox",
          "enum": [
            "api",
            "api.sandbox"
          ]
        }
      }
    }
  ],
  "security": [],
  "paths": {
    "/api/sessions/": {
      "parameters": [
        {
          "$ref": "#/components/parameters/AuthenticationBearerTokenHeader"
        },
        {
          "$ref": "#/components/parameters/MerchantAccountHeader"
        },
        {
          "$ref": "#/components/parameters/IdempotencyKeyHeader"
        },
        {
          "$ref": "#/components/parameters/APIVersionHeader"
        }
      ],
      "post": {
        "tags": [
          "Fully Hosted Sessions"
        ],
        "summary": "Create a Fully Hosted Session",
        "description": "A `POST` request to `/sessions/` initiates a `Session` of the Fully Hosted Forage Checkout UI. On success, the API creates a Forage [`Order`](ref:orders).\n\nThe response payload represents the [Fully Hosted `Session`](ref:forage-sessions#fully-hosted-session). The `ref` and `redirect_url` fields are the most important:\n  - `ref` represents the `Order`\n    - Store this `ref` so that you can pass it in a future request to [Retrieve the Order](ref:create-order) outcome\n  - `redirect_url` is the URL that launches the customer-facing Forage Session UI\n    - Point customers to this URL when they’re ready to complete checkout\n\n## Important Fully Hosted Session parameters\n\n### Pass the `tax_rate` of every item in the `product_list` so that Forage can handle taxes\n\nForage 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](ref:get-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.\n\n### Pass `customer_id` to speed up the request and prefill stored payment methods\n\n`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`.**\n\nWhen 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.\n\nEach 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.\n\nSee these guides for additional information:\n\n- [How Forage Fully Hosted integrations work](https://docs.joinforage.app/docs/fully-hosted#how-it-works)\n- [Fully Hosted Quickstart](https://docs.joinforage.app/docs/fully-hosted-quickstart)\n- [Fully Hosted `Session` payload](ref:forage-sessions#fully-hosted-session)\n",
        "operationId": "Create session",
        "security": [
          {
            "OAuth2": [
              "pinpad_only",
              "hosted_checkout"
            ]
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/FullyHostedSession"
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/FullyHostedSession200"
          },
          "400": {
            "description": "__Bad request__ - The request was not accepted because of an error in the request body or path.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseObject"
                },
                "examples": {
                  "cannot_parse_request_body": {
                    "summary": "Cannot Parse Request Body",
                    "value": {
                      "path": "/api/sessions/",
                      "errors": [
                        {
                          "code": "cannot_parse_request_body",
                          "message": "Parsing 'success_redirect_url' field failed with message: This field is required.",
                          "source": {
                            "resource": "Sessions",
                            "ref": ""
                          }
                        }
                      ]
                    }
                  },
                  "invalid_customer_id": {
                    "summary": "Invalid Customer ID",
                    "value": {
                      "path": "/api/sessions/",
                      "errors": [
                        {
                          "code": "invalid_customer_id",
                          "message": "No such customer: {psp_customer_id}",
                          "source": {
                            "resource": "Sessions",
                            "ref": ""
                          }
                        }
                      ]
                    }
                  },
                  "invalid_input_data": {
                    "summary": "Invalid Input Data",
                    "value": {
                      "path": "/api/sessions/",
                      "errors": [
                        {
                          "code": "invalid_input_data",
                          "message": "Query parameter missing or incomplete.",
                          "source": {
                            "resource": "Sessions",
                            "ref": ""
                          }
                        }
                      ]
                    }
                  },
                  "invalid_merchant_account": {
                    "summary": "Invalid Merchant Account",
                    "value": {
                      "path": "/api/sessions/",
                      "errors": [
                        {
                          "code": "invalid_merchant_account",
                          "message": "Merchant account Merchant ID not valid.",
                          "source": {
                            "resource": "Merchants"
                          }
                        }
                      ]
                    }
                  },
                  "missing_idempotency_key": {
                    "summary": "Missing Idempotency Key",
                    "value": {
                      "path": "/api/sessions/",
                      "errors": [
                        {
                          "code": "missing_idempotency_key",
                          "message": "You must include a value for the IDEMPOTENCY-KEY header in your requests to this endpoint.",
                          "source": {
                            "resource": "Idempotency_Key"
                          }
                        }
                      ]
                    }
                  },
                  "missing_merchant_account": {
                    "summary": "Missing Merchant Account",
                    "value": {
                      "path": "/api/sessions/",
                      "errors": [
                        {
                          "code": "missing_merchant_account",
                          "message": "No merchant account was provided.",
                          "source": {
                            "resource": "Merchants"
                          }
                        }
                      ]
                    }
                  },
                  "unknown_fields_error": {
                    "summary": "Unknown Fields Error",
                    "value": {
                      "path": "/api/sessions/",
                      "errors": [
                        {
                          "code": "unknown_fields_error",
                          "message": "Unknown field(s) provided: {unknown_fields}",
                          "source": {
                            "resource": "Sessions"
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseObject"
                },
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid Token",
                    "value": {
                      "path": "/api/sessions/",
                      "errors": [
                        {
                          "code": "invalid_token",
                          "message": "Incorrect authentication credentials.",
                          "source": {
                            "resource": "Accounts",
                            "ref": ""
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseObject"
                },
                "examples": {
                  "cannot_change_request": {
                    "summary": "Cannot Change Request",
                    "value": {
                      "path": "/api/orders/sessions/",
                      "errors": [
                        {
                          "code": "cannot_change_request",
                          "message": "Two requests were submitted with the same idempotency key, but slightly different request bodies. Please use a new idempotency key if you intended to change the request body",
                          "source": {
                            "resource": "Idempotency_Key"
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "423": {
            "$ref": "#/components/responses/Error423"
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseObject"
                },
                "examples": {
                  "too_many_requests": {
                    "summary": "Too Many Requests",
                    "value": {
                      "path": "/api/sessions/",
                      "errors": [
                        {
                          "code": "too_many_requests",
                          "message": "Request was throttled, please try again later.",
                          "source": {
                            "resource": "Sessions",
                            "ref": ""
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseObject"
                },
                "examples": {
                  "unknown_server_error": {
                    "summary": "Unknown Server Error",
                    "value": {
                      "path": "/api/sessions/",
                      "errors": [
                        {
                          "code": "unknown_server_error",
                          "message": "Unknown exception from EBT network",
                          "source": {
                            "resource": "Unknown"
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorsArray": {
        "type": "array",
        "description": "An array with information about the error.",
        "items": {
          "type": "object",
          "properties": {
            "code": {
              "type": "string",
              "description": "A short string that represents the error."
            },
            "message": {
              "type": "string",
              "description": "A developer-facing message with more details about the error, not to be displayed to customers."
            },
            "source": {
              "type": "object",
              "properties": {
                "resource": {
                  "type": "string",
                  "description": "The type of the Forage resource involved in the error."
                },
                "ref": {
                  "type": "string",
                  "description": "If applicable, the ten character reference hash of the Forage resource that caused the error. An empty string if no specific individual resource was involved."
                }
              }
            },
            "details": {
              "type": "object",
              "description": "Additional details about the error, if applicable."
            }
          }
        },
        "example": []
      },
      "ErrorResponseObject": {
        "type": "object",
        "description": "An object that includes details about the error.",
        "properties": {
          "path": {
            "type": "string",
            "description": "The requested endpoint."
          },
          "errors": {
            "$ref": "#/components/schemas/ErrorsArray"
          }
        }
      },
      "SessionRequest": {
        "type": "object",
        "description": "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.\n",
        "required": [
          "delivery_address",
          "success_redirect_url",
          "cancel_redirect_url"
        ],
        "properties": {
          "success_redirect_url": {
            "type": "string",
            "description": "The URL that Forage should redirect your customer to if the `Order` is completed successfully."
          },
          "cancel_redirect_url": {
            "type": "string",
            "description": "The URL that Forage should redirect your customer to if the `Order` is cancelled."
          },
          "delivery_address": {
            "$ref": "#/components/schemas/DeliveryAddressData"
          },
          "is_delivery": {
            "type": "boolean",
            "description": "Whether the order is for delivery or pickup. Optional — defaults to `false`. Forage reports this value to FNS for regulatory purposes."
          },
          "is_commercial_shipping": {
            "type": "boolean",
            "nullable": true,
            "description": "Whether the order is to be shipped commercially. FNS uses this value in its database for statistics."
          },
          "supported_benefits": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "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).\n"
          },
          "platform_fee": {
            "type": "number",
            "format": "decimal",
            "description": "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.",
            "example": 0.05
          },
          "customer_id": {
            "$ref": "#/components/schemas/CustomerIDField"
          },
          "external_order_id": {
            "$ref": "#/components/schemas/ExternalOrderIDField"
          },
          "external_location_id": {
            "$ref": "#/components/schemas/ExternalLocationIDField"
          }
        }
      },
      "FullyHostedSessionResponse": {
        "type": "object",
        "description": "The response payload represents a Fully Hosted Forage `Session`, an instance of the ready-to-use Forage Checkout UI.",
        "required": [
          "ref",
          "snap_total",
          "ebt_cash_total",
          "remaining_total",
          "product_list",
          "delivery_address",
          "is_delivery",
          "success_redirect_url",
          "cancel_redirect_url",
          "supported_benefits",
          "psp_customer_id",
          "customer_id",
          "external_order_id",
          "external_location_id",
          "status",
          "success_date",
          "receipt",
          "expires_at",
          "is_commercial_shipping",
          "redirect_url",
          "errors"
        ],
        "properties": {
          "ref": {
            "type": "string",
            "description": "A unique reference hash for the `Order` created for this `Session`.",
            "example": "93410bcaff"
          },
          "snap_total": {
            "type": "string",
            "format": "currency",
            "description": "The SNAP eligible portion of the order cost in USD, represented as a numeric string. Precision is supported to the penny.",
            "example": "25.99"
          },
          "ebt_cash_total": {
            "type": "string",
            "format": "currency",
            "description": "The portion of the `Order` total, in USD, that is EBT Cash eligible only, represented as a numeric string. Precision is supported to the penny.",
            "example": "5.99"
          },
          "remaining_total": {
            "type": "string",
            "format": "currency",
            "description": "The portion of the `Order` total, in USD, that is neither SNAP eligible nor EBT Cash eligible, represented as a numeric string. This amount must be charged to a credit or debit card, with precision supported to the penny.",
            "example": "10.99"
          },
          "product_list": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProductDataResponse"
            },
            "description": "A list of products in the customer's cart at checkout.\n\n> ⚠️ Required Fields\n>\n> Each item must include the following **required** fields:\n>\n>  - `name`\n>  - `upc`\n>  - `unit_price`\n>  - `quantity`\n>  - `eligibility`\n\nIf there are no taxes applied to any of the products, then you can pass an empty array as the value.\n\n_This field is returned as `null` in the case of a Custom `Session`_.\n",
            "example": []
          },
          "platform_fee": {
            "type": "string",
            "format": "decimal",
            "description": "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. Represented as a decimal string.",
            "example": "0.05"
          },
          "delivery_address": {
            "$ref": "#/components/schemas/DeliveryAddressData"
          },
          "is_delivery": {
            "type": "boolean",
            "description": "Whether the order is for delivery or pickup. This information is required per FNS regulations. Defaults to `false` if not provided.",
            "example": true
          },
          "success_redirect_url": {
            "type": "string",
            "description": "The URL that Forage should redirect your customer to if the `Order` is completed successfully.",
            "example": "https://www.your-app.com/?status=SUCCEEDED"
          },
          "cancel_redirect_url": {
            "type": "string",
            "description": "The URL that Forage should redirect your customer to if the `Order` is cancelled.",
            "example": "https://www.your-app.com/?status=CANCELED"
          },
          "supported_benefits": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "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).\n",
            "example": [
              "snap",
              "non_ebt"
            ]
          },
          "psp_customer_id": {
            "type": "string",
            "nullable": true,
            "description": "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.\n\n_This field is returned as `null` in the case of a Custom `Session`_.\n\n**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.\n",
            "example": "cus_AJ6yA7mRH34mJT"
          },
          "customer_id": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CustomerIDField"
              }
            ],
            "nullable": true,
            "example": "my_user_id"
          },
          "external_order_id": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ExternalOrderIDField"
              }
            ],
            "nullable": true
          },
          "external_location_id": {
            "type": "string",
            "nullable": true,
            "description": "A unique identifier for the physical fulfillment location."
          },
          "status": {
            "type": "string",
            "description": "The status is always `draft` at the start.",
            "enum": [
              "draft",
              "processing",
              "failed",
              "succeeded",
              "canceled"
            ],
            "example": "draft"
          },
          "success_date": {
            "type": "string",
            "nullable": true,
            "format": "date-time",
            "description": "A UTC timestamp that indicates when all of the `Payments` associated with the `Order` are successfully charged, represented as an [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string.",
            "example": "2021-06-16T00:11:50.000000Z"
          },
          "receipt": {
            "nullable": true,
            "allOf": [
              {
                "$ref": "#/components/schemas/ReceiptData"
              }
            ]
          },
          "expires_at": {
            "type": "string",
            "nullable": true,
            "format": "date-time",
            "description": "A UTC timestamp of when the `Order` associated with the `Session` will expire if it is not captured or canceled, set to 30 minutes from when the `Order` is created.",
            "example": "2024-02-05T19:41:37.334897Z"
          },
          "is_commercial_shipping": {
            "type": "boolean",
            "nullable": true,
            "description": "Whether the order is to be shipped commercially. FNS uses this value in its database for statistics."
          },
          "redirect_url": {
            "type": "string",
            "format": "url",
            "description": "The URL that launches the Forage Session UI. Point a customer to this URL when they are ready to complete checkout.",
            "example": "https://checkout.joinforage.app/payment?order=93410bcaff&merchant=1234567&payment_methods=62b4f98001&payment_methods=7401bea819"
          },
          "errors": {
            "description": "Always returned as an empty array on Session creation. Included for response-shape consistency with the underlying `Order` resource.",
            "allOf": [
              {
                "$ref": "#/components/schemas/ErrorsArray"
              }
            ]
          },
          "ebt_payment_method": {
            "type": "string",
            "description": "A unique reference hash for an existing Forage [`PaymentMethod`](ref:payment-methods). Use this param if you'd like to pre-populate the payment method field in the checkout UI for a returning customer.\n\n_This field is only returned in the response if it is passed in the original request body_.\n",
            "example": "ac47392bb1"
          }
        }
      },
      "FullyHostedSessionRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SessionRequest"
          },
          {
            "type": "object",
            "properties": {
              "product_list": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ProductData"
                },
                "description": "A list of products in the customer's cart at checkout.\n\n> ⚠️ Required Fields\n>\n> Each item must include the following **required** fields:\n>\n>  - `name`\n>  - `upc`\n>  - `unit_price`\n>  - `quantity`\n>  - `eligibility`\n\nIf there are no taxes applied to any of the products, then you can pass an empty array as the value.\n\n_This field is returned as `null` in the case of a Custom `Session`_.\n"
              },
              "psp_customer_id": {
                "type": "string",
                "description": "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.\n\n_This field is returned as `null` in the case of a Custom `Session`_.\n\n**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.\n",
                "example": "cus_AJ6yA7mRH34mJT"
              },
              "ebt_payment_method": {
                "type": "string",
                "description": "A unique reference hash for an existing Forage [`PaymentMethod`](ref:payment-methods). Use this param if you'd like to pre-populate the payment method field in the checkout UI for a returning customer.\n\n_This field is only returned in the response if it is passed in the original request body_.\n",
                "example": "ac47392bb1"
              }
            },
            "required": [
              "product_list"
            ]
          }
        ],
        "example": {
          "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",
              "funding_type": "ebt_snap"
            },
            "ebt_cash_payment": {
              "amount": 25.99,
              "metadata": {},
              "payment_method": "fsdf45345",
              "description": "An EBT Cash payment",
              "funding_type": "ebt_cash"
            }
          },
          "remaining_total": "5.99",
          "product_list": [
            {
              "name": "Apple",
              "upc": "033383087375",
              "unit_price": 2.99,
              "quantity": 5,
              "tax_rate": 0.015,
              "tax_rate_list": [
                {
                  "imposed_by": "California State Tax",
                  "tax_rate": 0.015
                }
              ],
              "eligibility": "snap"
            }
          ],
          "success_redirect_url": "https://www.your-app.com/?status=SUCCEEDED",
          "cancel_redirect_url": "https://www.your-app.com/?status=CANCELED"
        }
      },
      "BalanceResponse": {
        "type": "object",
        "description": "An object that represents an EBT cardholder's account balance.",
        "properties": {
          "id": {
            "type": "integer",
            "description": "The unique identifier for the balance record.",
            "example": 12345
          },
          "snap": {
            "type": "string",
            "format": "currency",
            "description": "The available SNAP balance in USD on the customer’s EBT Card, represented as a numeric string."
          },
          "non_snap": {
            "type": "string",
            "format": "currency",
            "description": "The available EBT Cash balance in USD on the customer's EBT Card, represented as a numeric string."
          },
          "updated": {
            "type": "string",
            "format": "date-time",
            "description": "A UTC timestamp that indicates when the funds in the account last changed, represented as an [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string."
          },
          "sequence_number": {
            "type": "string",
            "description": "A transaction number for this `PaymentMethod`'s most recent balance check. Returned only for POS Terminal transactions; omitted from online merchant balance checks."
          }
        }
      },
      "ProductData": {
        "type": "object",
        "required": [
          "name",
          "unit_price"
        ],
        "description": "Product information for an item in a customer's cart.",
        "properties": {
          "name": {
            "type": "string",
            "description": "The name of the product."
          },
          "upc": {
            "type": "string",
            "description": "The UPC of the product."
          },
          "gtin": {
            "type": "string",
            "description": "The GTIN (Global Trade Item Number) of the product."
          },
          "unit_price": {
            "type": "number",
            "format": "currency",
            "description": "The unit price of the product."
          },
          "quantity": {
            "type": "number",
            "format": "integer",
            "description": "The quantity of the product."
          },
          "tax_rate": {
            "type": "number",
            "format": "decimal",
            "description": "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%. 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`."
          },
          "tax_rate_list": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "imposed_by",
                "tax_rate"
              ],
              "properties": {
                "imposed_by": {
                  "type": "string",
                  "description": "The entity applying the tax to this item."
                },
                "tax_rate": {
                  "type": "number",
                  "format": "decimal",
                  "description": "The tax rate applied to the item by the entity described in the `imposed_by` field. If the product is subject to only one tax rate, then use the single `tax_rate` param instead of `tax_rate_list`."
                },
                "taxes_charged": {
                  "type": "number",
                  "format": "currency",
                  "description": "The portion of taxes charged for this item attributable to the `imposed_by` entity."
                },
                "taxes_exempted": {
                  "type": "number",
                  "format": "currency",
                  "description": "The portion of taxes exempted for this item attributable to the `imposed_by` entity."
                }
              }
            }
          },
          "taxes_charged": {
            "type": "number",
            "format": "currency",
            "description": "The amount of taxes charged for this item in USD."
          },
          "taxes_exempted": {
            "type": "number",
            "format": "currency",
            "description": "The amount of taxes exempted for this item in USD."
          },
          "tax_total": {
            "type": "number",
            "format": "currency",
            "description": "The total tax for this item in USD."
          },
          "eligibility": {
            "type": "string",
            "description": "The eligibility of the product. Must be `snap`, `ebt_cash`, or `non_ebt`.",
            "enum": [
              "snap",
              "ebt_cash",
              "non_ebt"
            ]
          }
        }
      },
      "ProductDataResponse": {
        "type": "object",
        "required": [
          "id",
          "name",
          "upc",
          "unit_price",
          "quantity",
          "eligibility",
          "snap_amount",
          "cash_amount",
          "credit_debit_amount",
          "tax_collected",
          "taxes_charged",
          "taxes_exempted"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "description": "The unique identifier for the product."
          },
          "name": {
            "type": "string",
            "description": "The name of the product."
          },
          "upc": {
            "type": "string",
            "nullable": true,
            "description": "The UPC of the product."
          },
          "gtin": {
            "type": "string",
            "description": "The GTIN (Global Trade Item Number) of the product."
          },
          "unit_price": {
            "type": "string",
            "format": "currency",
            "description": "The unit price of the product, represented as a numeric string."
          },
          "quantity": {
            "type": "integer",
            "description": "The quantity of the product."
          },
          "tax_rate": {
            "type": "string",
            "format": "decimal",
            "description": "The tax rate for the product, represented as a decimal string 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`."
          },
          "tax_rate_list": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "imposed_by",
                "tax_rate"
              ],
              "properties": {
                "imposed_by": {
                  "type": "string",
                  "description": "The entity applying the tax to this item."
                },
                "tax_rate": {
                  "type": "string",
                  "format": "decimal",
                  "description": "The tax rate applied to the item by the entity described in the `imposed_by` field, represented as a decimal string. If the product is subject to only one tax rate, then use the single `tax_rate` param instead of `tax_rate_list`."
                },
                "taxes_charged": {
                  "type": "string",
                  "format": "currency",
                  "nullable": true,
                  "description": "The portion of taxes charged for this item attributable to the `imposed_by` entity, represented as a numeric string."
                },
                "taxes_exempted": {
                  "type": "string",
                  "format": "currency",
                  "nullable": true,
                  "description": "The portion of taxes exempted for this item attributable to the `imposed_by` entity, represented as a numeric string."
                }
              }
            }
          },
          "eligibility": {
            "type": "string",
            "nullable": true,
            "enum": [
              "snap",
              "ebt_cash",
              "non_ebt"
            ],
            "description": "The eligibility of the product. Must be `snap`, `ebt_cash`, or `non_ebt`."
          },
          "snap_amount": {
            "type": "string",
            "format": "currency",
            "nullable": true,
            "description": "The amount paid for this product using SNAP benefits in USD, represented as a numeric string. Precision is supported to the penny."
          },
          "cash_amount": {
            "type": "string",
            "format": "currency",
            "nullable": true,
            "description": "The amount paid for this product using EBT Cash benefits in USD, represented as a numeric string. Precision is supported to the penny."
          },
          "credit_debit_amount": {
            "type": "string",
            "format": "currency",
            "nullable": true,
            "description": "The amount paid for this product using credit or debit card in USD, represented as a numeric string. Precision is supported to the penny."
          },
          "tax_collected": {
            "type": "string",
            "format": "currency",
            "nullable": true,
            "description": "The tax amount collected for this product in USD, represented as a numeric string. Precision is supported to the penny."
          },
          "taxes_charged": {
            "type": "string",
            "format": "currency",
            "nullable": true,
            "description": "The amount of taxes charged for this product in USD, represented as a numeric string. Precision is supported to the penny.",
            "example": "2.47"
          },
          "taxes_exempted": {
            "type": "string",
            "format": "currency",
            "nullable": true,
            "description": "The amount of taxes exempted for this product in USD, represented as a numeric string. Precision is supported to the penny.",
            "example": "1.83"
          }
        }
      },
      "DeliveryAddressData": {
        "type": "object",
        "required": [
          "line1",
          "zipcode"
        ],
        "description": "⚠️ **Exception**: If the purchase is made in-store via a POS Terminal, then a `delivery_address` is not required when creating a `Payment`.\n\nThe 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.\n",
        "properties": {
          "city": {
            "type": "string",
            "description": "The name of the city."
          },
          "country": {
            "type": "string",
            "description": "Either `us` or `US`. Defaults to `US` if not provided."
          },
          "line1": {
            "type": "string",
            "description": "The first line of the street address."
          },
          "line2": {
            "type": "string",
            "nullable": true,
            "description": "The second line of the street address."
          },
          "zipcode": {
            "type": "string",
            "description": "The zip or postal code."
          },
          "state": {
            "type": "string",
            "description": "The two-letter abbreviation, can be upper or lowercase, for the US state."
          }
        }
      },
      "ReceiptData": {
        "type": "object",
        "description": "Most of the information that you're required to display to the customer, according to FNS regulations.\n\nThis field is `null` if the data that populates the receipt is not yet available.\n\nThe total amount paid by the customer is `snap_amount` + `ebt_cash_amount` + `other_amount`. This amount will be settled with the merchant after applying Forage's fees.\n",
        "properties": {
          "ref_number": {
            "type": "string",
            "description": "A unique reference hash for the Forage `Order`, `Payment`, or `Refund` associated with this receipt.\n\nNote: `receipt.ref_number` equals `ref`.\n",
            "default": "45e3f12a90"
          },
          "is_voided": {
            "type": "boolean",
            "description": "Whether the transaction associated with this receipt has been voided. If `false`, then the transaction finished processing as expected. If `true`, then the transaction was reversed."
          },
          "snap_amount": {
            "type": "string",
            "description": "The USD amount charged/refunded to the SNAP balance of the EBT Card, represented as a numeric string.",
            "default": "25.99"
          },
          "ebt_cash_amount": {
            "type": "string",
            "format": "currency",
            "description": "The USD amount charged/refunded to the EBT Cash balance of the EBT Card, represented as a numeric string.",
            "default": "10.99"
          },
          "cash_back_amount": {
            "type": "string",
            "format": "currency",
            "nullable": true,
            "description": "The USD amount of cash back given to the customer, represented as a numeric string.",
            "default": "0.00"
          },
          "other_amount": {
            "type": "string",
            "format": "currency",
            "description": "The USD amount charged/refunded to any payment method that is not an EBT Card, represented as a numeric string.",
            "default": "5.99"
          },
          "sales_tax_applied": {
            "type": "string",
            "format": "currency",
            "description": "The USD amount of taxes charged to the customer’s non-EBT payment instrument, represented as a numeric string.",
            "default": "5.16"
          },
          "balance": {
            "nullable": true,
            "allOf": [
              {
                "$ref": "#/components/schemas/BalanceResponse"
              }
            ]
          },
          "last_4": {
            "type": "string",
            "description": "The last four digits of the EBT Card number.",
            "default": "3456"
          },
          "message": {
            "type": "string",
            "description": "A message from the EBT payment network that must be displayed to the EBT cardholder.",
            "default": "Approved"
          },
          "transaction_type": {
            "type": "string",
            "enum": [
              "Order",
              "Refund",
              "Payment"
            ],
            "description": "A constant string that is used to identify the transaction type associated with the receipt.\n",
            "default": "Refund"
          },
          "created": {
            "type": "string",
            "format": "date-time",
            "description": "A UTC timestamp of when the Forage transaction object was created, represented as an [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string.",
            "default": "2021-06-16T00:11:50.000000Z"
          },
          "sequence_number": {
            "type": "string",
            "nullable": true,
            "description": "The terminal transaction sequence number for POS transactions. `null` for online (non-POS) transactions."
          }
        }
      },
      "CustomerIDField": {
        "type": "string",
        "maxLength": 64,
        "description": "**⚠️ If you’re integrating Forage with a POS Terminal, then do not use this param. It is only supported for online transactions.**\n\nA unique identifier for the end customer making the payment.\n\nForage automatically adds the `customer_id` to the Session's corresponding `Order` and `OrderPayments`.\n\nThis 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.**\n\nIf you're providing your internal customer ID, then we recommend that you hash the value before sending it on the payload.\n\nEach 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.\n"
      },
      "ExternalOrderIDField": {
        "type": "string",
        "maxLength": 64,
        "description": "A unique identifier for the order as created by the merchant or platform (not Forage).\n\nWhen 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.\n\n**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.\n"
      },
      "ExternalLocationIDField": {
        "type": "string",
        "description": "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.\n",
        "example": "6e3b2ff7-51c8-4c64-befa-2eac90f7c3e9"
      }
    },
    "requestBodies": {
      "FullyHostedSession": {
        "description": "Pass the following fields in the body of the request to `/sessions/` to start a Fully Hosted `Session`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/FullyHostedSessionRequest"
            }
          }
        }
      }
    },
    "responses": {
      "FullyHostedSession200": {
        "description": "__OK__ - Success",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/FullyHostedSessionResponse"
            }
          }
        }
      },
      "Error423": {
        "description": "__Locked__ - The request could not be completed because the target resource is currently locked.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponseObject"
            },
            "examples": {
              "resource_locked": {
                "summary": "Resource Locked",
                "value": {
                  "path": "/api/example_path/",
                  "errors": [
                    {
                      "code": "resource_locked",
                      "message": "Request could not be completed because the resource is currently locked. Please try again later.",
                      "source": {
                        "resource": "Idempotency_Key",
                        "ref": ""
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "parameters": {
      "AuthenticationBearerTokenHeader": {
        "name": "Authorization",
        "in": "header",
        "description": "An OAuth 2.0 [authentication token](https://docs.joinforage.app/docs/authentication#authentication-tokens) that validates the request. Send a `POST` to the [`/o/token/`](ref:create-authentication-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>`.",
        "schema": {
          "type": "string"
        },
        "required": true
      },
      "MerchantAccountHeader": {
        "name": "Merchant-Account",
        "in": "header",
        "description": "A unique merchant ID that Forage provides during onboarding, as in `123ab45c67`. The Merchant ID can be found in the Forage [sandbox](https://dashboard.sandbox.joinforage.app/login/) or [production](https://dashboard.joinforage.app/login/) dashboard.",
        "schema": {
          "type": "string"
        },
        "required": true
      },
      "IdempotencyKeyHeader": {
        "name": "Idempotency-Key",
        "in": "header",
        "description": "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.",
        "schema": {
          "type": "string"
        },
        "required": true
      },
      "APIVersionHeader": {
        "name": "API-Version",
        "in": "header",
        "description": "The [Forage version](ref:version-history), represented as a string with the format of a `YYYY-MM-DD` date.\n\nIf not specified in the request header, then the version defaults to the value set in the Forage dashboard.\n",
        "schema": {
          "type": "string"
        },
        "required": false
      }
    },
    "securitySchemes": {
      "OAuth2": {
        "type": "oauth2",
        "description": "Pass the access token in the 'Authorization' header with the format \"Bearer ${token}\", i.e. the word \"Bearer\" and your access token from the /o/token/ API, separated by whitespace.\n",
        "flows": {
          "password": {
            "tokenUrl": "/o/token/",
            "scopes": {
              "hosted_checkout": "Scope for tokens used by merchant applications which allow Forage to manage split tender processing (i.e. EBT + Credit/Debit).\n",
              "pinpad_only": "Scope for tokens used by merchant applications which manage their own split tender (i.e. Forage Checkout is used only for EBT processing).\n"
            }
          },
          "clientCredentials": {
            "tokenUrl": "/o/token/",
            "scopes": {
              "internal": "Scope for tokens used by Forage internal applications.\n",
              "pin-protected": "Scope for tokens which can access secure storage.\n",
              "disbursement": "Scope for tokens which can disburse money to merchants.\n"
            }
          }
        }
      }
    }
  }
}
```