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

# Capture an EBT or HSA/FSA Payment

> 📘 Forage SDK Integrations And HSA/FSA Only
>
> This endpoint is only relevant to Forage SDK integrations and HSA/FSA payments.
>
> Instead of calling a front-end SDK method to capture a payment, you can use this endpoint to capture a payment from the backend.

A `POST` request to `/payments/{payment_ref}/capture_payment/` captures an existing Forage Payment.

On success, Forage automatically begins processing the charge to the customer, so this endpoint has immediate financial side effects.

The API responds with a [Payment](ref:payments) object that represents the transaction. For EBT payments the response also includes complete `receipt` information.

For HSA/FSA payments, the `capture_amount` must be less than or equal to the original `amount` field in the `Payment` object.

> ⚠️ Incompatible Fields for EBT Transactions
>
> Avoid using `capture_amount`, `qualified_healthcare_total`, `qualified_healthcare_subtotal`, and `product_list`. Including these fields in EBT transactions may cause unexpected behavior.

Once an HSA/FSA payment is captured, the `amount` field in the `Payment` object is updated to match the `capture_amount`. The originally authorized amount moves to the `authorization_amount` field, which is used only for debugging and bookkeeping.

> ⚠️ Capture Requests Must Be Server-Side
>
> To keep your app secure, requests to capture a payment should only be generated from the server-side.


# 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/payments/{payment_ref}/capture_payment/": {
      "parameters": [
        {
          "name": "payment_ref",
          "in": "path",
          "description": "A unique reference hash for the Forage `Payment` object, returned when the [`Payment` was created](ref:payments#create-a-payment).",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "$ref": "#/components/parameters/AuthenticationBearerTokenHeader"
        },
        {
          "$ref": "#/components/parameters/MerchantAccountHeader"
        },
        {
          "$ref": "#/components/parameters/IdempotencyKeyHeader"
        },
        {
          "$ref": "#/components/parameters/APIVersionHeader"
        }
      ],
      "post": {
        "tags": [
          "Deferred Capture"
        ],
        "summary": "Capture an EBT or HSA/FSA Payment",
        "x-readme": {
          "code-samples": [
            {
              "language": "curl",
              "code": "curl --request POST \\\n    --url https://api.sandbox.joinforage.app/api/payments/cc3175bfea/capture_payment/ \\\n    --header 'Authorization: Bearer <api_key>' \\\n    --header 'Merchant-Account: <merchant-id>' \\\n    --header 'Idempotency-Key: <idempotency-key>' \\\n    --header 'accept: application/json' \\\n    --header 'content-type: application/json' \\\n    --data '{\n  \"capture_amount\": 11.98,\n  \"qualified_healthcare_total\": 11.98,\n  \"qualified_healthcare_subtotal\": 11.98,\n  \"product_list\": [\n    {\n      \"gtin\": \"00041260013003\",\n      \"name\": \"Sample Healthcare Product\",\n      \"unit_price\": 5.99,\n      \"quantity\": 2,\n      \"eligibility\": \"hsa_fsa\"\n    }\n  ]\n}\n'\n"
            }
          ]
        },
        "description": "> 📘 Forage SDK Integrations And HSA/FSA Only\n>\n> This endpoint is only relevant to Forage SDK integrations and HSA/FSA payments.\n>\n> Instead of calling a front-end SDK method to capture a payment, you can use this endpoint to capture a payment from the backend.\n\nA `POST` request to `/payments/{payment_ref}/capture_payment/` captures an existing Forage Payment.\n\nOn success, Forage automatically begins processing the charge to the customer, so this endpoint has immediate financial side effects.\n\nThe API responds with a [Payment](ref:payments) object that represents the transaction. For EBT payments the response also includes complete `receipt` information.\n\nFor HSA/FSA payments, the `capture_amount` must be less than or equal to the original `amount` field in the `Payment` object.\n\n> ⚠️ Incompatible Fields for EBT Transactions\n>\n> Avoid using `capture_amount`, `qualified_healthcare_total`, `qualified_healthcare_subtotal`, and `product_list`. Including these fields in EBT transactions may cause unexpected behavior.\n\nOnce an HSA/FSA payment is captured, the `amount` field in the `Payment` object is updated to match the `capture_amount`. The originally authorized amount moves to the `authorization_amount` field, which is used only for debugging and bookkeeping.\n\n> ⚠️ Capture Requests Must Be Server-Side\n>\n> To keep your app secure, requests to capture a payment should only be generated from the server-side.\n",
        "operationId": "Capture a payment - deferred capture",
        "security": [
          {
            "OAuth2": [
              "internal",
              "pinpad_only"
            ]
          },
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/CapturePayment"
        },
        "responses": {
          "200": {
            "description": "__OK__ - Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseObject"
                },
                "examples": {
                  "ebt_error_05": {
                    "summary": "EBT Error - General Denial",
                    "value": {
                      "ref": "66ca7f3c35",
                      "merchant": "9777034",
                      "funding_type": "ebt_snap",
                      "amount": "1.00",
                      "description": "Testing app payments (SNAP Purchase)",
                      "metadata": {},
                      "payment_method": "6ef6acd145",
                      "delivery_address": null,
                      "is_delivery": false,
                      "created": "2024-05-07T11:04:58.967491-07:00",
                      "updated": "2024-05-07T11:05:15.432620-07:00",
                      "status": "failed",
                      "last_processing_error": null,
                      "success_date": null,
                      "receipt": {
                        "ref_number": "66ca7f3c35",
                        "is_voided": false,
                        "snap_amount": "1.00",
                        "ebt_cash_amount": "0.00",
                        "cash_back_amount": "0.00",
                        "other_amount": "0.00",
                        "sales_tax_applied": "0.00",
                        "balance": {
                          "snap": "72.94",
                          "non_snap": "32.16",
                          "updated": "2021-06-16T00:11:50.000000-07:00"
                        },
                        "last_4": "4443",
                        "message": "General denial - Cannot Process - Call Customer Service",
                        "transaction_type": "Payment",
                        "created": "2024-05-07T11:05:15.427552-07:00",
                        "sequence_number": "PA022ba7"
                      },
                      "expires_at": "2024-05-07T18:35:15.432620Z",
                      "pos_terminal": {
                        "terminal_id": "0783f5a4",
                        "provider_terminal_id": "Android Emulator"
                      },
                      "sequence_number": "PA022ba7",
                      "external_location_id": null,
                      "merchant_destination_account": "null,",
                      "errors": [
                        {
                          "code": "ebt_error_05",
                          "message": "General denial - Cannot Process - Call Customer Service",
                          "source": {
                            "resource": "Payments",
                            "ref": "66ca7f3c35"
                          }
                        }
                      ],
                      "previous_errors": [],
                      "refunds": []
                    }
                  },
                  "ebt_error_14": {
                    "summary": "EBT Error - Invalid Card Number",
                    "value": {
                      "ref": "66ca7f3c35",
                      "merchant": "9777034",
                      "funding_type": "ebt_snap",
                      "amount": "1.00",
                      "description": "Testing app payments (SNAP Purchase)",
                      "metadata": {},
                      "payment_method": "6ef6acd145",
                      "delivery_address": null,
                      "is_delivery": false,
                      "created": "2024-05-07T11:04:58.967491-07:00",
                      "updated": "2024-05-07T11:05:15.432620-07:00",
                      "status": "failed",
                      "last_processing_error": null,
                      "success_date": null,
                      "receipt": {
                        "ref_number": "66ca7f3c35",
                        "is_voided": false,
                        "snap_amount": "1.00",
                        "ebt_cash_amount": "0.00",
                        "cash_back_amount": "0.00",
                        "other_amount": "0.00",
                        "sales_tax_applied": "0.00",
                        "balance": {
                          "snap": "72.94",
                          "non_snap": "32.16",
                          "updated": "2021-06-16T00:11:50.000000-07:00"
                        },
                        "last_4": "4443",
                        "message": "Invalid card number - Re-enter Transaction",
                        "transaction_type": "Payment",
                        "created": "2024-05-07T11:05:15.427552-07:00",
                        "sequence_number": "PA022ba7"
                      },
                      "expires_at": "2024-05-07T18:35:15.432620Z",
                      "pos_terminal": {
                        "terminal_id": "0783f5a4",
                        "provider_terminal_id": "Android Emulator"
                      },
                      "sequence_number": "PA022ba7",
                      "external_location_id": null,
                      "merchant_destination_account": "null,",
                      "errors": [
                        {
                          "code": "ebt_error_14",
                          "message": "Invalid card number - Re-enter Transaction",
                          "source": {
                            "resource": "Payments",
                            "ref": "66ca7f3c35"
                          }
                        }
                      ],
                      "previous_errors": [],
                      "refunds": []
                    }
                  },
                  "ebt_error_41": {
                    "summary": "EBT Error - Lost Card",
                    "value": {
                      "ref": "66ca7f3c35",
                      "merchant": "9777034",
                      "funding_type": "ebt_snap",
                      "amount": "1.00",
                      "description": "Testing app payments (SNAP Purchase)",
                      "metadata": {},
                      "payment_method": "6ef6acd145",
                      "delivery_address": null,
                      "is_delivery": false,
                      "created": "2024-05-07T11:04:58.967491-07:00",
                      "updated": "2024-05-07T11:05:15.432620-07:00",
                      "status": "failed",
                      "last_processing_error": null,
                      "success_date": null,
                      "receipt": {
                        "ref_number": "66ca7f3c35",
                        "is_voided": false,
                        "snap_amount": "1.00",
                        "ebt_cash_amount": "0.00",
                        "cash_back_amount": "0.00",
                        "other_amount": "0.00",
                        "sales_tax_applied": "0.00",
                        "balance": {
                          "snap": "72.94",
                          "non_snap": "32.16",
                          "updated": "2021-06-16T00:11:50.000000-07:00"
                        },
                        "last_4": "4443",
                        "message": "Lost Card - Cannot Process - Call Customer Service",
                        "transaction_type": "Payment",
                        "created": "2024-05-07T11:05:15.427552-07:00",
                        "sequence_number": "PA022ba7"
                      },
                      "expires_at": "2024-05-07T18:35:15.432620Z",
                      "pos_terminal": {
                        "terminal_id": "0783f5a4",
                        "provider_terminal_id": "Android Emulator"
                      },
                      "sequence_number": "PA022ba7",
                      "external_location_id": null,
                      "merchant_destination_account": "null,",
                      "errors": [
                        {
                          "code": "ebt_error_41",
                          "message": "Lost Card - Cannot Process - Call Customer Service",
                          "source": {
                            "resource": "Payments",
                            "ref": "66ca7f3c35"
                          }
                        }
                      ],
                      "previous_errors": [],
                      "refunds": []
                    }
                  },
                  "ebt_error_51": {
                    "summary": "EBT Error - Insufficient Funds",
                    "value": {
                      "ref": "66ca7f3c35",
                      "merchant": "9777034",
                      "funding_type": "ebt_snap",
                      "amount": "1.00",
                      "description": "Testing app payments (SNAP Purchase)",
                      "metadata": {},
                      "payment_method": "6ef6acd145",
                      "delivery_address": null,
                      "is_delivery": false,
                      "created": "2024-05-07T11:04:58.967491-07:00",
                      "updated": "2024-05-07T11:05:15.432620-07:00",
                      "status": "failed",
                      "last_processing_error": null,
                      "success_date": null,
                      "receipt": {
                        "ref_number": "66ca7f3c35",
                        "is_voided": false,
                        "snap_amount": "1.00",
                        "ebt_cash_amount": "0.00",
                        "cash_back_amount": "0.00",
                        "other_amount": "0.00",
                        "sales_tax_applied": "0.00",
                        "balance": {
                          "snap": "72.94",
                          "non_snap": "32.16",
                          "updated": "2021-06-16T00:11:50.000000-07:00"
                        },
                        "last_4": "4443",
                        "message": "Insufficient funds - Insufficient Funds. Remaining balances are SNAP: {number}, EBT Cash: {number}",
                        "transaction_type": "Payment",
                        "created": "2024-05-07T11:05:15.427552-07:00",
                        "sequence_number": "PA022ba7"
                      },
                      "expires_at": "2024-05-07T18:35:15.432620Z",
                      "pos_terminal": {
                        "terminal_id": "0783f5a4",
                        "provider_terminal_id": "Android Emulator"
                      },
                      "sequence_number": "PA022ba7",
                      "external_location_id": null,
                      "merchant_destination_account": "null,",
                      "errors": [
                        {
                          "code": "ebt_error_51",
                          "message": "Insufficient funds - Insufficient Funds. Remaining balances are SNAP: {number}, EBT Cash: {number}",
                          "source": {
                            "resource": "Payments",
                            "ref": "66ca7f3c35"
                          },
                          "details": {
                            "cash_balance": "1000.00",
                            "snap_balance": "1000.00"
                          }
                        }
                      ],
                      "previous_errors": [],
                      "refunds": []
                    }
                  },
                  "ebt_error_55": {
                    "summary": "EBT Error - Invalid Pin",
                    "value": {
                      "ref": "66ca7f3c35",
                      "merchant": "9777034",
                      "funding_type": "ebt_snap",
                      "amount": "1.00",
                      "description": "Testing app payments (SNAP Purchase)",
                      "metadata": {},
                      "payment_method": "6ef6acd145",
                      "delivery_address": null,
                      "is_delivery": false,
                      "created": "2024-05-07T11:04:58.967491-07:00",
                      "updated": "2024-05-07T11:05:15.432620-07:00",
                      "status": "failed",
                      "last_processing_error": null,
                      "success_date": null,
                      "receipt": {
                        "ref_number": "66ca7f3c35",
                        "is_voided": false,
                        "snap_amount": "1.00",
                        "ebt_cash_amount": "0.00",
                        "cash_back_amount": "0.00",
                        "other_amount": "0.00",
                        "sales_tax_applied": "0.00",
                        "balance": {
                          "snap": "72.94",
                          "non_snap": "32.16",
                          "updated": "2021-06-16T00:11:50.000000-07:00"
                        },
                        "last_4": "4443",
                        "message": "Invalid PIN or PIN not selected - Invalid PIN",
                        "transaction_type": "Payment",
                        "created": "2024-05-07T11:05:15.427552-07:00",
                        "sequence_number": "PA022ba7"
                      },
                      "expires_at": "2024-05-07T18:35:15.432620Z",
                      "pos_terminal": {
                        "terminal_id": "0783f5a4",
                        "provider_terminal_id": "Android Emulator"
                      },
                      "sequence_number": "PA022ba7",
                      "external_location_id": null,
                      "merchant_destination_account": "null,",
                      "errors": [
                        {
                          "code": "ebt_error_55",
                          "message": "Invalid PIN or PIN not selected - Invalid PIN",
                          "source": {
                            "resource": "Payments",
                            "ref": "66ca7f3c35"
                          }
                        }
                      ],
                      "previous_errors": [],
                      "refunds": []
                    }
                  },
                  "ebt_error_75": {
                    "summary": "EBT Error - Pin Tries Exceeded",
                    "value": {
                      "ref": "66ca7f3c35",
                      "merchant": "9777034",
                      "funding_type": "ebt_snap",
                      "amount": "1.00",
                      "description": "Testing app payments (SNAP Purchase)",
                      "metadata": {},
                      "payment_method": "6ef6acd145",
                      "delivery_address": null,
                      "is_delivery": false,
                      "created": "2024-05-07T11:04:58.967491-07:00",
                      "updated": "2024-05-07T11:05:15.432620-07:00",
                      "status": "failed",
                      "last_processing_error": null,
                      "success_date": null,
                      "receipt": {
                        "ref_number": "66ca7f3c35",
                        "is_voided": false,
                        "snap_amount": "1.00",
                        "ebt_cash_amount": "0.00",
                        "cash_back_amount": "0.00",
                        "other_amount": "0.00",
                        "sales_tax_applied": "0.00",
                        "balance": {
                          "snap": "72.94",
                          "non_snap": "32.16",
                          "updated": "2021-06-16T00:11:50.000000-07:00"
                        },
                        "last_4": "4443",
                        "message": "PIN tries exceeded - PIN Tries Exceeded",
                        "transaction_type": "Payment",
                        "created": "2024-05-07T11:05:15.427552-07:00",
                        "sequence_number": "PA022ba7"
                      },
                      "expires_at": "2024-05-07T18:35:15.432620Z",
                      "pos_terminal": {
                        "terminal_id": "0783f5a4",
                        "provider_terminal_id": "Android Emulator"
                      },
                      "sequence_number": "PA022ba7",
                      "external_location_id": null,
                      "merchant_destination_account": "null,",
                      "errors": [
                        {
                          "code": "ebt_error_75",
                          "message": "PIN tries exceeded - PIN Tries Exceeded",
                          "source": {
                            "resource": "Payments",
                            "ref": "66ca7f3c35"
                          }
                        }
                      ],
                      "previous_errors": [],
                      "refunds": []
                    }
                  },
                  "ebt_error_90": {
                    "summary": "EBT Error - Host Not Available",
                    "value": {
                      "ref": "66ca7f3c35",
                      "merchant": "9777034",
                      "funding_type": "ebt_snap",
                      "amount": "1.00",
                      "description": "Testing app payments (SNAP Purchase)",
                      "metadata": {},
                      "payment_method": "6ef6acd145",
                      "delivery_address": null,
                      "is_delivery": false,
                      "created": "2024-05-07T11:04:58.967491-07:00",
                      "updated": "2024-05-07T11:05:15.432620-07:00",
                      "status": "failed",
                      "last_processing_error": null,
                      "success_date": null,
                      "receipt": {
                        "ref_number": "66ca7f3c35",
                        "is_voided": false,
                        "snap_amount": "1.00",
                        "ebt_cash_amount": "0.00",
                        "cash_back_amount": "0.00",
                        "other_amount": "0.00",
                        "sales_tax_applied": "0.00",
                        "balance": {
                          "snap": "72.94",
                          "non_snap": "32.16",
                          "updated": "2021-06-16T00:11:50.000000-07:00"
                        },
                        "last_4": "4443",
                        "message": "Processor not logged on - Host Not Available",
                        "transaction_type": "Payment",
                        "created": "2024-05-07T11:05:15.427552-07:00",
                        "sequence_number": "PA022ba7"
                      },
                      "expires_at": "2024-05-07T18:35:15.432620Z",
                      "pos_terminal": {
                        "terminal_id": "0783f5a4",
                        "provider_terminal_id": "Android Emulator"
                      },
                      "sequence_number": "PA022ba7",
                      "external_location_id": null,
                      "merchant_destination_account": "null,",
                      "errors": [
                        {
                          "code": "ebt_error_90",
                          "message": "Processor not logged on - Host Not Available",
                          "source": {
                            "resource": "Payments",
                            "ref": "66ca7f3c35"
                          }
                        }
                      ],
                      "previous_errors": [],
                      "refunds": []
                    }
                  },
                  "cannot_capture_payment_is_delivery": {
                    "summary": "Cannot Capture Payment - Missing 'is_delivery'",
                    "value": {
                      "path": "/api/payments/{payment_ref}/capture_payment/",
                      "errors": [
                        {
                          "code": "cannot_capture_payment",
                          "message": "is_delivery value is null. Payment with ref {payment.ref} requires a valid is_delivery value for capture.",
                          "source": {
                            "resource": "Payments",
                            "ref": "{payment_ref}"
                          }
                        }
                      ]
                    }
                  },
                  "cannot_capture_payment_null_amount": {
                    "summary": "Cannot Capture Payment - Amount is null",
                    "value": {
                      "path": "/api/payments/{payment_ref}/capture_payment/",
                      "errors": [
                        {
                          "code": "cannot_capture_payment",
                          "message": "Amount value is null. Payment with ref {payment.ref} with funding_type {payment.funding_type} cannot be captured with a null amount value",
                          "source": {
                            "resource": "Payments",
                            "ref": "{payment_ref}"
                          }
                        }
                      ]
                    }
                  },
                  "fixed_settlement_not_applicable": {
                    "summary": "Fixed Settlement Not Applicable",
                    "value": {
                      "path": "/api/payments/{payment_ref}/capture_payment/",
                      "errors": [
                        {
                          "code": "fixed_settlement_not_applicable",
                          "message": "The merchant_fixed_settlement and platform_fixed_settlement fields are only applicable to EBT Cash Payments.",
                          "source": {
                            "resource": "Payments",
                            "ref": "{payment_ref}"
                          }
                        }
                      ]
                    }
                  },
                  "insufficient_funds": {
                    "summary": "Insufficient Funds",
                    "value": {
                      "path": "/api/payments/{payment_ref}/capture_payment/",
                      "errors": [
                        {
                          "code": "ebt_error_51",
                          "message": "Insufficient funds - Insufficient Funds. Remaining balances are SNAP: 1.23, EBT Cash: 4.56",
                          "details": {
                            "snapBalance": 1.23,
                            "cashBalance": 4.56
                          }
                        }
                      ]
                    }
                  },
                  "invalid_input_data": {
                    "summary": "Invalid Input Data",
                    "value": {
                      "path": "/api/payments/{payment_ref}/capture_payment/",
                      "errors": [
                        {
                          "code": "invalid_input_data",
                          "message": "Query parameter unrecognized.",
                          "source": {
                            "resource": "Payments",
                            "ref": "{payment_ref}"
                          }
                        }
                      ]
                    }
                  },
                  "invalid_merchant_account": {
                    "summary": "Invalid Merchant Account",
                    "value": {
                      "path": "/api/payments/{payment_ref}/capture_payment/",
                      "errors": [
                        {
                          "code": "invalid_merchant_account",
                          "message": "Merchant account FNS number not valid.",
                          "source": {
                            "resource": "Merchants"
                          }
                        }
                      ]
                    }
                  },
                  "missing_idempotency_key": {
                    "summary": "Missing Idempotency Key",
                    "value": {
                      "path": "/api/payments/{payment_ref}/capture_payment/",
                      "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/payments/{payment_ref}/capture_payment/",
                      "errors": [
                        {
                          "code": "missing_merchant_account",
                          "message": "No merchant account was provided.",
                          "source": {
                            "resource": "Merchants"
                          }
                        }
                      ]
                    }
                  },
                  "pin_retrieval_error": {
                    "summary": "Pin Retrieval Error",
                    "value": {
                      "path": "/api/payments/{payment_ref}/capture_payment/",
                      "errors": [
                        {
                          "code": "pin_retrieval_error",
                          "message": "Unable to find encrypted PIN for key value",
                          "source": {
                            "resource": "Payments"
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseObject"
                },
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid Token",
                    "value": {
                      "path": "/api/payments/{payment_ref}/capture_payment/",
                      "errors": [
                        {
                          "code": "invalid_token",
                          "message": "Invalid Token",
                          "source": {
                            "resource": "OAuth_Access_Tokens"
                          }
                        }
                      ]
                    }
                  },
                  "expired_session_token": {
                    "summary": "Expired Session Token",
                    "value": {
                      "path": "/api/payments/{payment_ref}/capture_payment/",
                      "errors": [
                        {
                          "code": "expired_session_token",
                          "message": "This token has expired",
                          "source": {
                            "resource": "Session_Token"
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseObject"
                },
                "examples": {
                  "cannot_capture_payment": {
                    "summary": "Cannot Capture Payment - Payment Status",
                    "value": {
                      "path": "/api/payments/{payment_ref}/capture_payment/",
                      "errors": [
                        {
                          "code": "cannot_capture_payment",
                          "message": "Payment with ref {payment_ref} is either processing, succeeded, or canceled and therefore cannot be captured.",
                          "source": {
                            "resource": "Payments",
                            "ref": "{payment_ref}"
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseObject"
                },
                "examples": {
                  "resource_not_found": {
                    "summary": "Payment Not Found",
                    "value": {
                      "path": "/api/payments/{payment_ref}/capture_payment/",
                      "errors": [
                        {
                          "code": "resource_not_found",
                          "message": "Payment with ref {payment_ref} does not exist.",
                          "source": {
                            "resource": "Payments",
                            "ref": "{payment_ref}"
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseObject"
                },
                "examples": {
                  "cannot_change_request": {
                    "summary": "Cannot Change Request",
                    "value": {
                      "path": "/api/payments/{payment_ref}/capture_payment/",
                      "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"
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseObject"
                },
                "examples": {
                  "too_many_requests": {
                    "summary": "Too Many Requests",
                    "value": {
                      "path": "/api/payments/{payment_ref}/capture_payment/",
                      "errors": [
                        {
                          "code": "too_many_requests",
                          "message": "Request was throttled, please try again later.",
                          "source": {
                            "resource": "Payments"
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseObject"
                },
                "examples": {
                  "unknown_server_error": {
                    "summary": "Unknown Server Error",
                    "value": {
                      "path": "/api/payments/{payment_ref}/capture_payment/",
                      "errors": [
                        {
                          "code": "unknown_server_error",
                          "message": "Unknown exception from EBT network",
                          "source": {
                            "resource": "Unknown"
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseObject"
                },
                "examples": {
                  "ebt_processor_timeout": {
                    "summary": "EBT processor timeout",
                    "value": {
                      "path": "/api/payments/{payment_ref}/capture_payment/",
                      "errors": [
                        {
                          "code": "ebt_processor_timeout",
                          "message": "Unable to contact EBT processor, please try again shortly.",
                          "source": {
                            "resource": "Payments",
                            "ref": "{payment_ref}"
                          }
                        }
                      ]
                    }
                  },
                  "pin_retrieval_error": {
                    "summary": "Pin Retrieval Error",
                    "value": {
                      "path": "/api/payments/{payment_ref}/capture_payment/",
                      "errors": [
                        {
                          "code": "pin_retrieval_error",
                          "message": "Unable to retrieve encrypted PIN value",
                          "source": {
                            "resource": "Payments"
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "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"
          }
        }
      },
      "CapturePaymentRequest": {
        "type": "object",
        "description": "A request body to pass to `/payments/{payment_ref}/capture_payment/` to capture a previously authorized HSA/FSA payment.",
        "properties": {
          "capture_amount": {
            "type": "string",
            "format": "decimal",
            "description": "The amount to capture, in USD.",
            "example": "11.98"
          },
          "qualified_healthcare_total": {
            "type": "string",
            "format": "decimal",
            "description": "The total amount of qualified healthcare items in the order after discounts, including tax, shipping, and fees, in USD.",
            "example": "11.98"
          },
          "qualified_healthcare_subtotal": {
            "type": "string",
            "format": "decimal",
            "description": "The total amount of qualified healthcare items in the order before any discounts, adjustments, taxes, or fees, in USD.",
            "example": "11.98"
          },
          "product_list": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProductDataHsaFsa"
            },
            "description": "A list of products that a customer has in their cart at checkout."
          }
        },
        "required": [
          "capture_amount",
          "qualified_healthcare_total",
          "qualified_healthcare_subtotal",
          "product_list"
        ]
      },
      "PaymentRequest": {
        "type": "object",
        "description": "This object represents a single payment. It is associated with a single payment method.",
        "properties": {
          "amount": {
            "type": "string",
            "format": "decimal",
            "description": "A positive decimal number that represents how much to charge the [`PaymentMethod`](ref:payment-methods) in USD. Precision is supported to the penny. The minimum amount that can be charged is `0.01`. To differentiate between a SNAP and an EBT Cash charge on the same EBT Card, use the `funding_type` field. If you need to charge both funding types, then create a `Payment` for each charge."
          },
          "funding_type": {
            "type": "string",
            "description": "The payment instrument type. Use this field to differentiate between a SNAP (`ebt_snap`) and an EBT Cash (`ebt_cash`) charge on the same EBT Card. If you need to charge both funding types, then create a `Payment` for each charge. Use `credit_payfac` for all charges to HSA/FSA cards. `credit_tpp` is the funding type assigned to non-EBT payment objects created via a Fully Hosted Checkout integration.",
            "enum": [
              "ebt_snap",
              "ebt_cash",
              "credit_tpp",
              "credit_payfac",
              "benefit",
              "wic"
            ]
          },
          "payment_method": {
            "type": "string",
            "description": "The unique reference hash for the existing Forage [`PaymentMethod`](ref:payment-methods) that is to be charged in this transaction.\n\n⚠️ **Exception**: POS integrations do not need to provide a `payment_method` when creating a payment.\n"
          },
          "delivery_address": {
            "$ref": "#/components/schemas/DeliveryAddressData"
          },
          "is_delivery": {
            "type": "boolean",
            "description": "⚠️ **Exception**: If the purchase is made in-store via a POS Terminal, then a `is_delivery` is not required when creating a `Payment`.\n\nWhether the order is for delivery or pickup. This information is required per FNS regulations. Defaults to `false` if not provided.\n"
          },
          "description": {
            "type": "string",
            "description": "A description of the payment."
          },
          "metadata": {
            "$ref": "#/components/schemas/MetadataObject"
          },
          "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."
          },
          "platform_fixed_settlement": {
            "type": "string",
            "format": "decimal",
            "description": "The fixed amount in USD that a platform takes from EBT Cash payments prior to splitting by the `platform_fee`. Precision is supported to the penny."
          },
          "merchant_fixed_settlement": {
            "type": "string",
            "format": "decimal",
            "description": "The fixed amount in USD that should be restored to the merchant from EBT Cash payments prior to splitting by the `platform_fee`. Precision is supported to the penny."
          },
          "tpp_lookup_id": {
            "type": "string",
            "description": "An identifier for the credit/debit TPP.\n\nFor Stripe integrations, the client secret for a Stripe `PaymentIntent`.\n",
            "example": "pi_1DpdZq2eZvKYlo2CAYyzTr8j_secret_lxr4crBJP4txbrg7sqit0XQQO"
          },
          "customer_id": {
            "$ref": "#/components/schemas/CustomerIDField"
          },
          "external_order_id": {
            "$ref": "#/components/schemas/ExternalOrderIDField"
          },
          "merchant_destination_account": {
            "type": "string",
            "description": "A unique reference hash for the bank account that is to receive funds settlement for this payment. Use this field if you're settling funds across multiple merchant bank accounts. Reach out to your Forage account manager for details on generating a hash.\n\nDefaults to the hash for the default merchant bank account if not provided.\n"
          },
          "pos_terminal": {
            "type": "object",
            "description": "**⚠️  This param is only supported for POS Terminal integrations. Do not use this param for online transactions.**\n\nAn object that details information about the POS Terminal that processes the payment.\n",
            "properties": {
              "provider_terminal_id": {
                "type": "string",
                "description": "A unique string that identifies the POS Terminal."
              }
            }
          },
          "external_location_id": {
            "$ref": "#/components/schemas/ExternalLocationIDField"
          }
        },
        "required": [
          "funding_type"
        ]
      },
      "PaymentResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PaymentRequest"
          },
          {
            "type": "object",
            "properties": {
              "ref": {
                "type": "string",
                "description": "A unique reference hash for the Forage `Payment` object.\n\n_Note:_ `receipt.ref_number` equals `ref`.\n\nYou need to pass this value to the front-end SDK method that captures the payment.\n"
              },
              "merchant": {
                "type": "string",
                "description": "A string that represents a unique merchant ID that Forage provides during onboarding."
              },
              "status": {
                "type": "string",
                "description": "The status of the `Payment`. One of:\n\n- `canceled`: The `Payment`object can't be used.\n- `failed`: If the error is temporary, then this `Payment` can be resubmitted for capture without modification. Check the `receipt.message` field for a description of the error.\n- `processing`: The outcome of the `Payment` is pending.\n- `requires_confirmation`: The `Payment` hasn't been submitted for processing.\n- `succeeded`: The `Payment` has been successfully processed and will be included in settlement. It can't be changed.\n- `authorized`: The `Payment` has been authorized, but not yet captured. Only applicable to HSA payments.\n",
                "enum": [
                  "requires_confirmation",
                  "processing",
                  "canceled",
                  "succeeded",
                  "failed",
                  "authorized"
                ]
              },
              "created": {
                "type": "string",
                "format": "date-time",
                "description": "A UTC timestamp of when the `Payment` was created, represented as an [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string."
              },
              "updated": {
                "type": "string",
                "format": "date-time",
                "description": "A UTC timestamp of that indicates when the `Payment` was last modified, represented as an [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string."
              },
              "expires_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "A UTC timestamp of when the `Payment` will expire if it is not captured or canceled, set to 30 minutes from when the `Payment` is created.\n\nIf the `status` of the `Payment` is `succeeded` or `canceled`, then the `expires_at` value is `null`.\n"
              },
              "success_date": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "A UTC timestamp of when the `Payment` was successfully processed, represented as an [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string. This value is `null` until the Payment enters the `succeeded` or `partial_capture` states."
              },
              "refunds": {
                "type": "array",
                "description": "References to the `Refund`s attached to this payment. The format depends on the `with_refunds` query parameter:\n\n- **Default behavior** (when `with_refunds` is `false` or omitted): Array of refund reference strings\n- **Expanded behavior** (when `with_refunds=true`): Array of full `Refund` objects with complete refund details\n",
                "items": {
                  "type": "string",
                  "description": "Refund reference string"
                }
              },
              "receipt": {
                "type": "object",
                "nullable": true,
                "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"
              },
              "last_processing_error": {
                "type": "object",
                "nullable": true,
                "description": "The `code` and `message` values corresponding to the most recent [Payments API error](ref:errors#payments-api-errors). Always `null` when the `Payment` is created."
              },
              "previous_errors": {
                "$ref": "#/components/schemas/ErrorsArray"
              },
              "address_postal_code_check": {
                "type": "string",
                "nullable": true,
                "description": "The result of any check done on the delivery address zip code. One of:\n- `pass`: The provided information is correct and matches the data on file with the card issuer.\n- `fail`: The provided information is incorrect and does not match the data on file.\n- `unavailable`: The card issuer will not perform the check.\n- `unchecked`: The information was provided but has not yet been checked by the card issuer.\n",
                "enum": [
                  "pass",
                  "fail",
                  "unavailable",
                  "unchecked"
                ],
                "example": "pass"
              },
              "cvc_check": {
                "type": "string",
                "nullable": true,
                "description": "The result of any check done on the CVC. One of:\n- `pass`: The provided information is correct and matches the data on file with the card issuer.\n- `fail`: The provided information is incorrect and does not match the data on file.\n- `unavailable`: The card issuer will not perform the check.\n- `unchecked`: The information was provided but has not yet been checked by the card issuer.\n",
                "enum": [
                  "pass",
                  "fail",
                  "unavailable",
                  "unchecked"
                ],
                "example": "pass"
              },
              "delivery_address": {
                "type": "object",
                "nullable": true,
                "description": "The delivery or pickup address for the order, passed to the EBT network. Returns an address object with `line1`, `line2`, `city`, `state`, `zipcode`, and `country`. Null when no delivery address is set."
              },
              "is_delivery": {
                "type": "boolean",
                "nullable": true,
                "description": "Whether the order is for delivery or pickup. Null when not specified."
              }
            },
            "required": [
              "ref",
              "status",
              "created",
              "updated"
            ]
          }
        ],
        "example": {
          "amount": "25.99",
          "funding_type": "ebt_snap",
          "payment_method": "ac47392bb1",
          "delivery_address": {
            "city": "San Francisco",
            "country": "US",
            "line1": "1856 Market St.",
            "zipcode": "94106",
            "state": "CA"
          },
          "is_delivery": true,
          "description": "An EBT Payment",
          "metadata": {},
          "platform_fee": "0.05",
          "platform_fixed_settlement": "5.11",
          "merchant_fixed_settlement": "5.95",
          "customer_id": "cus_1234567890",
          "external_order_id": "1f2ee410-5b47-4130-aec2-40f5eb2108f5",
          "merchant_destination_account": "1bdefaa456",
          "pos_terminal": {
            "provider_terminal_id": "tbd123"
          },
          "external_location_id": "6e3b2ff7-51c8-4c64-befa-2eac90f7c3e9",
          "ref": "cc3175bfea",
          "merchant": "9000055",
          "status": "requires_confirmation",
          "created": "2021-06-16T00:11:50.000000Z",
          "updated": "2021-06-16T00:11:50.000000Z",
          "expires_at": "2021-06-16T00:41:50.000000Z",
          "success_date": "2021-06-16T00:11:50.000000Z",
          "refunds": [
            "ac47392bb1"
          ],
          "receipt": {
            "ref_number": "cc3175bfea",
            "is_voided": true,
            "snap_amount": "25.99",
            "ebt_cash_amount": "10.99",
            "other_amount": "5.99",
            "sales_tax_applied": "5.16",
            "balance": {
              "snap": "72.94",
              "non_snap": "32.16",
              "updated": "2021-06-16T00:11:50.000000Z"
            },
            "last_4": "3456",
            "message": "Approved",
            "transaction_type": "Payment",
            "created": "2021-06-16T00:11:50.000000Z"
          },
          "last_processing_error": null,
          "previous_errors": []
        }
      },
      "ProductDataHsaFsa": {
        "type": "object",
        "required": [
          "name",
          "unit_price",
          "quantity",
          "eligibility"
        ],
        "description": "Product information for an item in a customer's cart. Include either UPC or GTIN for each item.",
        "properties": {
          "name": {
            "type": "string",
            "description": "The name of the product.",
            "example": "Sample Healthcare Product"
          },
          "upc": {
            "type": "string",
            "description": "The UPC of the product.",
            "example": "04126001300"
          },
          "gtin": {
            "type": "string",
            "description": "The GTIN of the product.",
            "example": "00041260013003"
          },
          "unit_price": {
            "type": "number",
            "format": "currency",
            "description": "The unit price of the product.",
            "example": 5.99
          },
          "quantity": {
            "type": "number",
            "format": "integer",
            "description": "The quantity of the product.",
            "example": 2
          },
          "eligibility": {
            "type": "string",
            "nullable": true,
            "description": "The eligibility of the product. Must be `hsa_fsa` for HSA/FSA products. This can be set to `null`, `snap`, `ebt_cash`, or `non_ebt` for other products.",
            "enum": [
              "hsa_fsa",
              "snap",
              "ebt_cash",
              "non_ebt"
            ]
          }
        }
      },
      "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."
          }
        }
      },
      "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"
      },
      "MetadataObject": {
        "type": "object",
        "description": "A required object containing merchant-defined key-value pairs to provide additional context for the payment.\n\nMerchants 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.\n\nPass an empty object (`{}`) if no additional information is available.\n\n> ⚠️ Personally Identifiable Information\n>\n> **Do not include personally identifiable information (PII)** such as names, emails, or payment details.\n"
      }
    },
    "requestBodies": {
      "CapturePayment": {
        "description": "A request body to pass to `/payments/{payment_ref}/capture_payment/`. Required for HSA/FSA payments.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/CapturePaymentRequest"
            }
          }
        }
      }
    },
    "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"
            }
          }
        }
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Pass the access token in the 'Authorization' header with the format \"Bearer ${token}\", i.e. the word \"Bearer\" and your JWT bearer token from the /api/session_token/ end-point, separated by whitespace.\n"
      }
    }
  }
}
```