---
title: "Create a Custom Payment Capture Session"
method: POST
path: "/api/capture_sessions/"
tags: ["Custom Sessions"]
---

# Create a Custom Payment Capture Session

`POST /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](https://docs.joinforage.app/reference/forage-sessions#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](https://docs.joinforage.app/reference/create-order-payment), or to check the status of the `Order` via a `GET` to [`/orders/{order_ref}/`](https://docs.joinforage.app/reference/get-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}/`](https://docs.joinforage.app/reference/get-order).

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

## Request body

- CustomCaptureSessionRequest — 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` DeliveryAddressData, 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.
    - `city` string — The name of the city.
    - `country` string — Either `us` or `US`. Defaults to `US` if not provided.
    - `line1` string, required — The first line of the street address.
    - `line2` string, nullable — The second line of the street address.
    - `zipcode` string, required — The zip or postal code.
    - `state` string — The two-letter abbreviation, can be upper or lowercase, for the US state.
  - `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, nullable — Whether the order is to be shipped commercially. FNS uses this value in its database for statistics.
  - `supported_benefits` string[] — 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_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 — **⚠️ 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 — 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.
    - `snap_payment` PaymentDetail
      - `amount` number, required — A positive decimal number that represents how much to charge the `PaymentMethod` in USD. Precision is supported to the penny. To charge multiple balances, add both a `snap_payment` and `ebt_cash_payment` object to the `payment_details` list. The minimum amount that can be charged is `0.01`.
      - `metadata` MetadataObject, required — A required object containing merchant-defined key-value pairs to provide additional context for the payment. Merchants should use this field to store **reference information** relevant to the transaction (for example, order details, system identifiers, or tracking data). This helps link the payment to records within their system. Pass an empty object (`{}`) if no additional information is available. > ⚠️ Personally Identifiable Information > > **Do not include personally identifiable information (PII)** such as names, emails, or payment details.
      - `payment_method` string, required — The unique reference hash for the existing Forage [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods) that is to be charged in this transaction.
      - `description` string, required — A string that describes the payment.
      - `funding_type` string — A string that represents the type of tender. Use `ebt_cash` for `ebt_cash_payment` and `ebt_snap` for `snap_payment`.
    - `ebt_cash_payment` PaymentDetail
      - `amount` number, required — A positive decimal number that represents how much to charge the `PaymentMethod` in USD. Precision is supported to the penny. To charge multiple balances, add both a `snap_payment` and `ebt_cash_payment` object to the `payment_details` list. The minimum amount that can be charged is `0.01`.
      - `metadata` MetadataObject, required — A required object containing merchant-defined key-value pairs to provide additional context for the payment. Merchants should use this field to store **reference information** relevant to the transaction (for example, order details, system identifiers, or tracking data). This helps link the payment to records within their system. Pass an empty object (`{}`) if no additional information is available. > ⚠️ Personally Identifiable Information > > **Do not include personally identifiable information (PII)** such as names, emails, or payment details.
      - `payment_method` string, required — The unique reference hash for the existing Forage [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods) that is to be charged in this transaction.
      - `description` string, required — A string that describes the payment.
      - `funding_type` string — A string that represents the type of tender. Use `ebt_cash` for `ebt_cash_payment` and `ebt_snap` for `snap_payment`.

## Response `200`

__OK__ - Success

- object — 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.
  - `ref` string — 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_date` string, 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](https://www.iso.org/iso-8601-date-and-time-format.html) string.
  - `receipt` object — Most of the information that you're required to display to the customer, according to FNS regulations. This field is `null` if the data that populates the receipt is not yet available. The 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.
    - `ref_number` string — A unique reference hash for the Forage `Order`, `Payment`, or `Refund` associated with this receipt. Note: `receipt.ref_number` equals `ref`.
    - `is_voided` boolean — 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` string — The USD amount charged/refunded to the SNAP balance of the EBT Card, represented as a numeric string.
    - `ebt_cash_amount` string, currency — The USD amount charged/refunded to the EBT Cash balance of the EBT Card, represented as a numeric string.
    - `cash_back_amount` string, currency, nullable — The USD amount of cash back given to the customer, represented as a numeric string.
    - `other_amount` string, currency — The USD amount charged/refunded to any payment method that is not an EBT Card, represented as a numeric string.
    - `sales_tax_applied` string, currency — The USD amount of taxes charged to the customer’s non-EBT payment instrument, represented as a numeric string.
    - `balance` BalanceResponse — An object that represents an EBT cardholder's account balance.
      - `id` integer — The unique identifier for the balance record.
      - `snap` string, currency — The available SNAP balance in USD on the customer’s EBT Card, represented as a numeric string.
      - `non_snap` string, currency — The available EBT Cash balance in USD on the customer's EBT Card, represented as a numeric string.
      - `updated` string, date-time — 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` string — A transaction number for this `PaymentMethod`'s most recent balance check. Returned only for POS Terminal transactions; omitted from online merchant balance checks.
    - `last_4` string — The last four digits of the EBT Card number.
    - `message` string — A message from the EBT payment network that must be displayed to the EBT cardholder.
    - `transaction_type` 'Order' | 'Refund' | 'Payment' — A constant string that is used to identify the transaction type associated with the receipt.
    - `created` string, date-time — 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.
    - `sequence_number` string, nullable — The terminal transaction sequence number for POS transactions. `null` for online (non-POS) transactions.
  - `expires_at` string — 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_shipping` boolean, nullable — Whether the order is to be shipped commercially. FNS uses this value in its database for statistics.
  - `redirect_url` string, url — The URL that launches the Forage Session UI. Point a customer to this URL when they are ready to complete checkout.
  - `previous_errors` object[] — An array with information about the error.
    - `code` string — A short string that represents the error.
    - `message` string — A developer-facing message with more details about the error, not to be displayed to customers.
    - `source` object
      - `resource` string — The type of the Forage resource involved in the error.
      - `ref` string — 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` object — Additional details about the error, if applicable.
  - `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` DeliveryAddressData, 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.
    - `city` string — The name of the city.
    - `country` string — Either `us` or `US`. Defaults to `US` if not provided.
    - `line1` string, required — The first line of the street address.
    - `line2` string, nullable — The second line of the street address.
    - `zipcode` string, required — The zip or postal code.
    - `state` string — The two-letter abbreviation, can be upper or lowercase, for the US state.
  - `is_delivery` boolean — Whether the order is for delivery or pickup. Optional — defaults to `false`. Forage reports this value to FNS for regulatory purposes.
  - `supported_benefits` string[] — 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_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 — **⚠️ 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 — 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.
    - `snap_payment` PaymentDetail
      - `amount` number, required — A positive decimal number that represents how much to charge the `PaymentMethod` in USD. Precision is supported to the penny. To charge multiple balances, add both a `snap_payment` and `ebt_cash_payment` object to the `payment_details` list. The minimum amount that can be charged is `0.01`.
      - `metadata` MetadataObject, required — A required object containing merchant-defined key-value pairs to provide additional context for the payment. Merchants should use this field to store **reference information** relevant to the transaction (for example, order details, system identifiers, or tracking data). This helps link the payment to records within their system. Pass an empty object (`{}`) if no additional information is available. > ⚠️ Personally Identifiable Information > > **Do not include personally identifiable information (PII)** such as names, emails, or payment details.
      - `payment_method` string, required — The unique reference hash for the existing Forage [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods) that is to be charged in this transaction.
      - `description` string, required — A string that describes the payment.
      - `funding_type` string — A string that represents the type of tender. Use `ebt_cash` for `ebt_cash_payment` and `ebt_snap` for `snap_payment`.
    - `ebt_cash_payment` PaymentDetail
      - `amount` number, required — A positive decimal number that represents how much to charge the `PaymentMethod` in USD. Precision is supported to the penny. To charge multiple balances, add both a `snap_payment` and `ebt_cash_payment` object to the `payment_details` list. The minimum amount that can be charged is `0.01`.
      - `metadata` MetadataObject, required — A required object containing merchant-defined key-value pairs to provide additional context for the payment. Merchants should use this field to store **reference information** relevant to the transaction (for example, order details, system identifiers, or tracking data). This helps link the payment to records within their system. Pass an empty object (`{}`) if no additional information is available. > ⚠️ Personally Identifiable Information > > **Do not include personally identifiable information (PII)** such as names, emails, or payment details.
      - `payment_method` string, required — The unique reference hash for the existing Forage [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods) that is to be charged in this transaction.
      - `description` string, required — A string that describes the payment.
      - `funding_type` string — A string that represents the type of tender. Use `ebt_cash` for `ebt_cash_payment` and `ebt_snap` for `snap_payment`.

## Other responses

- `400` — __Bad request__ - The request was not accepted because of an error in the request body or path.
- `401` — Unauthorized
- `409` — Conflict
- `423` — __Locked__ - The request could not be completed because the target resource is currently locked.
- `429` — Too Many Requests
- `500` — Internal Server Error

---

[API](https://skmtc.dev/joinforage/apis/forage-payments-api.md) · [All operations](https://skmtc.dev/joinforage/apis/forage-payments-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/joinforage/forage-payments-api/revisions/4b7212706fae/schema)