# Forage Documentation > Discover Forage’s API Documentation Hub, featuring detailed guides and references to integrate EBT and SNAP payment solutions seamlessly. Build better with Forage today! ## Guides - [Errors](https://docs.joinforage.app/docs/custom-errors.md): Error documentation for Custom integrations - [Quickstart](https://docs.joinforage.app/docs/custom-quickstart.md): Use the prebuilt Forage Custom UI to collect a customer's EBT Card PIN and process EBT payments in your website and app. - [Reuse Payment Methods](https://docs.joinforage.app/docs/custom-reuse-payment-methods.md): Allow your customers to reuse their saved payment methods in Custom Checkout. - [Introduction](https://docs.joinforage.app/docs/custom.md) - [Errors](https://docs.joinforage.app/docs/fully-hosted-errors.md): Error documentation for Fully Hosted integrations - [Quickstart](https://docs.joinforage.app/docs/fully-hosted-quickstart.md) - [Reuse Payment Methods](https://docs.joinforage.app/docs/fully-hosted-reuse-payment-methods.md): Allow your customers to reuse their saved payment methods in Fully Hosted Checkout. - [Introduction](https://docs.joinforage.app/docs/fully-hosted.md) - [EBT Standards and Integration Reference](https://docs.joinforage.app/docs/ebt-integration-reference.md): Merchant prerequisites, item eligibility tagging, FNS-compliant terminology, SDK versions, and a feature comparison. - [EBT Payments 101](https://docs.joinforage.app/docs/ebt-payments.md): The key industry players and payment methods in the EBT ecosystem. - [How Forage Works](https://docs.joinforage.app/docs/how-forage-works.md): The six-phase Forage partnership process, from FNS authorization to launch and growth. - [Integration Options](https://docs.joinforage.app/docs/integration-options.md): A decision guide for choosing between Fully Hosted Checkout, Custom Checkout, online-only SDKs, and the POS Terminal SDK. - [Understanding Forage Authentication](https://docs.joinforage.app/docs/authentication-concepts.md): Learn how Forage bearer tokens work and when to use each type. - [Authentication Token Reference](https://docs.joinforage.app/docs/authentication-reference.md): Endpoints and SDK methods that require Forage bearer tokens. - [Authenticate with Forage](https://docs.joinforage.app/docs/authentication.md): Generate authentication and session tokens for Forage API requests. - [Webhooks Overview](https://docs.joinforage.app/docs/configure-webhooks.md): Configure real-time updates about orders, payments, and refunds with Forage webhooks. - [How Forage Webhooks Work](https://docs.joinforage.app/docs/webhooks-concepts.md): Understand what webhooks are, when events fire, and how Forage delivers them - [How to Configure Webhooks](https://docs.joinforage.app/docs/webhooks-configure.md): Set up a webhook endpoint, register it in the Forage dashboard, and verify signatures - [Reference: Webhook Events](https://docs.joinforage.app/docs/webhooks-event-reference.md): Complete specifications for all Forage webhook events, payload schemas, and IP addresses - [Set up a Forage integration](https://docs.joinforage.app/docs/setup.md): Everything you need to create an account, register an app, and authenticate with the Forage API. - [Register an App](https://docs.joinforage.app/docs/register-an-app.md): Learn how to register an app with Forage and access API credentials. - [Sign up for Forage](https://docs.joinforage.app/docs/sign-up-for-forage.md): Create an account and update Forage Checkout settings. - [Enable HSA/FSA Payments](https://docs.joinforage.app/docs/enable-hsa-fsa-payments.md): Learn how to enable HSA/FSA payments effortlessly using your existing Forage EBT integration. - [iOS HSA/FSA Quickstart](https://docs.joinforage.app/docs/ios-hsa-fsa-quickstart.md): Use the Forage iOS SDK to accept HSA/FSA payments in your iOS app. - [JS HSA/FSA Quickstart](https://docs.joinforage.app/docs/js-hsa-fsa-quickstart.md): Use the Forage JavaScript SDK to accept HSA/FSA payments online. - [Taxes](https://docs.joinforage.app/docs/about-taxes.md) - [Defer EBT Payment Capture and Refund Completion to the Server](https://docs.joinforage.app/docs/capture-ebt-payments-server-side.md): Learn how to use the Forage Payments API and SDKs to defer EBT payment capture and refund completion to the server. - [Classify Your Product Catalog](https://docs.joinforage.app/docs/catalog-assistant.md): Automatically identify HSA/FSA-eligible products using Forage's Catalog Assistant - [Navigating the EBT Chip Card Transition with Forage](https://docs.joinforage.app/docs/ebt-chip-card-transition.md): What POS platforms need to know about the EBT chip card transition to stay ready - [Process EBT SNAP refunds](https://docs.joinforage.app/docs/ebt-refunds.md): Learn how to process partial refunds for online SNAP and EBT payments, including FNS requirements and developer implementation options. - [Platform Settlement](https://docs.joinforage.app/docs/platform-settlement.md) - [Receipts and Confirmation Screens](https://docs.joinforage.app/docs/receipts.md): Learn about FNS requirements for transaction records and how to extract the data - [Restrict Forms of Tender](https://docs.joinforage.app/docs/supported-benefits.md) - [Test Cards](https://docs.joinforage.app/docs/test-cards.md): Simulate EBT and HSA/FSA transactions in your Forage integration with this complete list of test card numbers for sandbox validation and error handling. - [Introduction](https://docs.joinforage.app/docs/android.md): Accept EBT payments in your Android mobile app - [Quickstart](https://docs.joinforage.app/docs/forage-android-quickstart.md): Use the Forage Android SDK to accept online-only EBT SNAP payments in your mobile app. - [Style Android Elements](https://docs.joinforage.app/docs/forage-android-styling-guide.md): Learn how to style Forage Elements when building with the Android SDK - [Style iOS Elements](https://docs.joinforage.app/docs/forage-ios-styling-guide.md): Learn how to style Forage Elements when building with the iOS SDK - [Quickstart](https://docs.joinforage.app/docs/ios-quickstart.md): Use the Forage iOS SDK to accept EBT SNAP payments in your iOS app. - [Introduction](https://docs.joinforage.app/docs/ios.md): Add EBT payments to your iOS app - [Quickstart](https://docs.joinforage.app/docs/forage-js-quickstart.md): Learn about the Forage JS methods and Payments API endpoints that you need to interact with to accept EBT SNAP online. - [Introduction](https://docs.joinforage.app/docs/forage-js.md): Add EBT payments to your web application - [Errors](https://docs.joinforage.app/docs/sdk-errors.md): Error documentation for SDK integration-related endpoints - [Quickstart](https://docs.joinforage.app/docs/forage-terminal-android.md): Use the Forage Terminal SDK to accept EBT SNAP and other payment methods via a POS system. - [Introduction](https://docs.joinforage.app/docs/pos-terminal-sdk.md): Accept in-store EBT SNAP payments - [Reporting Overview](https://docs.joinforage.app/docs/reporting-overview.md): Learn about Forage's three report types and how to access them via Dashboard, API, or SFTP—each suited to different business sizes and technical needs. - [Merchant (Charging to Merchant) CSV Report](https://docs.joinforage.app/docs/csv-report-merch-merch.md): CSV report for merchants who pay Forage fees directly. Includes Payout Transaction Reports and a Payout Summary for easy reconciliation and settlement tracking. - [Merchant (Charging to Platform) CSV Report](https://docs.joinforage.app/docs/csv-report-merch-plat.md): CSV report for merchants where the platform pays Forage fees. Includes Payout Transaction Reports and a Payout Summary for easy reconciliation and settlement tracking. - [Platform CSV Report](https://docs.joinforage.app/docs/csv-report-plat.md): CSV report for platforms managing multiple merchants. Includes Payout Transaction Reports and a Payout Summary for easy reconciliation and settlement tracking. - [SFTP Reports](https://docs.joinforage.app/docs/sftp-reports.md): Learn how Forage generates and delivers daily CSV reports via SFTP. Includes report types, formatting standards, and setup instructions for merchants and platforms. - [Understanding Transaction Type and Payment Method](https://docs.joinforage.app/docs/transaction-type-and-payment-method.md): This guide explains Forage's `transaction_type` and `payment_method` fields, available in Transaction Reports. - [EBT Refund Failures on Frozen Cards](https://docs.joinforage.app/docs/ebt-refund-failure.md): Learn how support teams can identify and fix EBT refund failures caused by frozen cards, including resolving the ebt_error_62 error code. ## API Reference - [Bulk revoke authentication tokens](https://docs.joinforage.app/reference/bulk-revoke-auth-tokens.md): > 📘 Authentication Guide > > For comprehensive details about authenticating with the Forage API, refer to the [authentication guide](doc:authentication). A `POST` request to `/o/bulk_revoke/` deletes a specified number of [authentication tokens](doc:authentication#authentication-tokens). Tokens are revoked in chronological order based on expiry time. For example, setting `revoke_count` to `50` deletes the `50` oldest tokens. The `revoke_count` value can range between `1` and `1000`. - [Create an authentication token](https://docs.joinforage.app/reference/create-authentication-token.md): > ⚠️ Use Session Tokens In Production > > To keep your app secure, long-lived authentication tokens in production are only for server-side requests. Client-side requests in production must use [session tokens](ref:create-session-token). > 📘 Managing OAuth Token Expiration > > OAuth tokens expire after **7 days** by default (604800 seconds), but can be configured to expire sooner or up to 30 days. There can be up to 1000 active authentication tokens for a Client ID and Client Secret pair at any given time. To manage the number of active authentication tokens, use the [`/o/revoke_token/`](ref:revoke-authentication-token) endpoint to revoke a single token, or [`/o/bulk_revoke/`](ref:bulk-revoke-auth-tokens) to revoke in bulk. > 📘 Authentication Guide > > Check out the Forage [authentication guide](doc:authentication) for more details on authentication tokens. A `POST` request to `/o/token/` creates a new authentication token. The token is returned as the `access_token` value in the response body. An authentication token is a long-lived OAuth 2.0 bearer token that validates requests from your backend to Forage. Pass an authentication token in the `Authorization` header of server-side requests to handle sensitive tasks like creating an order or capturing a payment. You need your app's Client ID and Client Secret from the Forage dashboard ([sandbox](https://dashboard.sandbox.joinforage.app/), [production](https://dashboard.joinforage.app/)) to generate an authentication token. If you don't yet have dashboard access, then please [get in touch](https://www.joinforage.com/get-in-touch). - [Create a session token](https://docs.joinforage.app/reference/create-session-token.md): > 📘 Authentication Guide > > For comprehensive details about authenticating with the Forage API, refer to the [authentication guide](doc:authentication). > 📘 Session Token Length > > Session tokens are short-lived and expire after fifteen minutes. > ⚠️ Authentication Token Required > > You need to create an [authentication token](ref:create-authentication-token) before you can generate a session token. A `POST` request to `/session_token/` creates a new session token. The token is returned as the `token` value in the response body. A session token is a temporary OAuth 2.0 bearer token that expires after 15 minutes. Session tokens are used in client-side requests. For example, `POST`s to [create a Payment Method](ref:create-payment-method) require session tokens in the `Authorization` header, and session tokens are passed as parameters to [SDK methods](doc:authentication#sdk-methods-that-require-session-tokens) that submit customer data. - [Bearer Tokens](https://docs.joinforage.app/reference/bearer-tokens.md): A bearer token is an authentication credential that validates your requests to the Forage API - [Revoke an authentication token](https://docs.joinforage.app/reference/revoke-authentication-token.md): > 📘 Authentication Guide > > For comprehensive details about authenticating with the Forage API, refer to the [authentication guide](doc:authentication). A `POST` request to `/o/revoke_token/` revokes a previously created [authentication token](doc:authentication#authentication-tokens). You need your app's Client ID and Client Secret from the Forage dashboard ([sandbox](https://dashboard.sandbox.joinforage.app/), [production](https://dashboard.joinforage.app/)) to revoke an authentication token. If you don't yet have dashboard access, then please [get in touch](https://www.joinforage.com/get-in-touch). > 📘 Active Token Limits > > There can be up to 1000 active authentication tokens for a Client ID and Client Secret pair at any given time. - [Retrieve state card details](https://docs.joinforage.app/reference/retrieve-state-card-details.md): This endpoint returns a predefined list of U.S. states, associated card BINs, and acceptable PAN (Primary Account Number) lengths. The data is static and designed for consumption by SDKs and partner integrations to facilitate client-side validation of state-specific card details. Each entry in the response includes a two-letter state code, the corresponding BIN, and an array of valid PAN lengths for that state. This endpoint is particularly useful for ensuring consistency and accuracy in front-end validation processes. - [Create a PaymentMethod](https://docs.joinforage.app/reference/create-payment-method.md): A `POST` request to `/payment_methods/` creates a new representation of a customer's payment instrument in Forage's database. > 📘 **Tokenization vs. Network Validation** > > **Tokenization (this endpoint)**: Forage validates card format, BIN support, and merchant configuration. The EBT network is NOT contacted during tokenization. **Card validity can only be confirmed after attempting a balance check or payment with the processor.** > > **Network validation**: Occurs later during balance checks or payments when the EBT network validates the card, PIN, and account status. | Stage | Who validates | When it happens | Example errors | |-------|---------------|-----------------|----------------| | Tokenization | Forage | `POST /payment_methods` | invalid PAN, unsupported BIN/state, throttling | | Processing | EBT network | balance check or payment | card closed, insufficient funds, wrong PIN | > ⚠️ **BIN Blocking Scope** > > Forage blocks known BINs from restricted states (Guam, Virgin Islands) where online EBT is not supported. However, Forage does not block unregistered BINs. An unregistered BIN may pass tokenization but will fail during processing when the EBT network rejects the card. On success, the API responds with a Forage `PaymentMethod` object. You need to retrieve and store the `ref` value for future requests. For example: - To get the outcome of a balance inquiry, you need to pass the `ref` as the path param in a request to [Retrieve a `PaymentMethod`](ref:get-payment-method). - To [Create a `Payment`](ref:create-a-payment), you need to pass the `ref` as the `payment_method` request body param. ### When to use the `Merchant-Account` Header The `Merchant-Account` Header requirements vary by payment method type: - **For EBT payment methods**: The `Merchant-Account` header is **optional** - **For HSA/FSA payment methods**: The `Merchant-Account` header is **required** - **For credit/debit payment methods**: The `Merchant-Account` header is **required** The `Merchant-Account` header is required for all payment methods except EBT due to technical requirements for routing and payout processing. **EBT PaymentMethods are tenant-scoped.** An EBT `PaymentMethod` created under one merchant account can be used by other merchant accounts within the same tenant. The `Merchant-Account` header does not restrict EBT `PaymentMethod` usability across merchant accounts within the same tenant. When `Merchant-Account` is passed, the created `PaymentMethod` is associated with that specific merchant account for routing and reporting purposes. For EBT payment methods, the `PaymentMethod` remains usable across all merchant accounts within the same tenant. > 📘 SDK Behavior > > Forage JS automatically includes the `Merchant-Account` header from initialization when creating `PaymentMethod`s. There is currently no option to omit this header during `PaymentMethod` creation. > 📘 Use `customer_id` When Creating PaymentMethods > > Pass `customer_id` in the request to Create a `PaymentMethod`. `customer_id` helps Forage's servers more quickly identify and associate the correct customer with the `PaymentMethod`. While `customer_id` is not technically a required parameter, if you omit it then the request to create the `PaymentMethod` could take longer to process. **It is strongly recommended to pass `customer_id`.** > > Additionally, passing `customer_id` enables Forage to throttle card additions per customer, helping prevent abuse and fraud. > > Each customer should only have one unique `customer_id`. For example, if you create both a `PaymentMethod` and a `Payment` for the same customer, then the `customer_id` should be the same in both requests to ensure continuity of stored payment methods. > 📘 State Validation > > To check which states and BINs Forage supports, use the [Retrieve state card details](ref:retrieve-state-card-details) endpoint. This is useful for customers concerned with state waivers or validating card eligibility before tokenization. See these guides for more information: - [How Custom integrations work](doc:custom#how-it-works) - [Custom Quickstart](doc:custom-quickstart) - [Delete a PaymentMethod](https://docs.joinforage.app/reference/delete-payment-method.md): A `DELETE` request to `/payment_methods/{payment_method_ref}/` deletes a representation of a customer's payment instrument in Forage's database. Returns an empty object if the operation was successful. > 📘 Cannot Delete Succeeded `PaymentMethod` > > If a `PaymentMethod` has any associated payments in the `succeeded` state, then the `PaymentMethod` cannot be deleted. > ⚠️ Deleting `PaymentMethod` > > Deleting a `PaymentMethod` cannot be undone. Use this endpoint with caution. - [Retrieve a PaymentMethod](https://docs.joinforage.app/reference/get-payment-method.md): A `GET` request to `/payment_methods/{payment_method_ref}/` retrieves the specified [`PaymentMethod` object](ref:payment-methods#paymentmethod-object). You can use this endpoint to, for example: - Retrieve the `balance` of an EBT Card after a customer completes a [Custom Balance Check Session](ref:create-custom-balance-check-session) - Retrieve information about a reusable payment method to display in a digital wallet - [Payment Methods](https://docs.joinforage.app/reference/payment-methods.md): The Forage `PaymentMethod` object represents a customer's payment instrument. - [Update a PaymentMethod](https://docs.joinforage.app/reference/update-payment-method.md): A `PATCH` request to `/payment_methods/{payment_method_ref}/` modifies information about an existing `PaymentMethod`. You can add a `customer_id` if it was not set when the `PaymentMethod` was created, or update whether the card is `reusable`. Returns a [`PaymentMethod` object](ref:payment-methods#paymentmethod-object) if the operation is successful. - [Retrieve an Order Report](https://docs.joinforage.app/reference/get-order-report.md): > 📘 Fully Hosted And Custom Integrations Only > > Order Reports are only relevant to Fully Hosted and Custom integrations. Only Fully Hosted and Custom integrations generate Forage `Orders`. Use any of the other `/reporting/` endpoints if you're building with an SDK. A `GET` request to `/reporting/orders/` retrieves an Order Report. On success, the API returns a list of Forage `Orders` created during the provided reporting period. - [Retrieve a Payout Report](https://docs.joinforage.app/reference/get-payout-report.md): A `GET` request to `/reporting/payouts/` retrieves a [Payout Report](ref:reports#payout-summary-reports). A payout is a scheduled funds disbursement from Forage to a merchant. A payout accounts for all transactions, both purchases and refunds, during the scheduled time period. On success, the API returns a list of payouts that occurred between the provided `start_date` and `end_date`. - [Retrieve a Payout Transaction Report](https://docs.joinforage.app/reference/get-payout-transaction-report.md): A `GET` request to `/reporting/payouts/{payout_id}/transactions/` retrieves a [Payout Transaction Report](ref:reports#payout-transaction-reports). A Payout Transaction Report includes a list of all transactions associated with the provided `payout_id`. Forage defines a transaction as any financial operation that triggers a flow of funds, including both EBT purchases and EBT refunds. > ⚠️ Credit/Debit Settlement Handled By PSP > > Credit and debit card transactions are included in the report if the transaction occurred via a Fully Hosted integration, but Forage is never involved in the settlement flow for credit/debit. That falls to the [credit/debit PSP](doc:ebt-online-101#creditdebit-payment-service-provider-psp), so balance your credit/debit accounting against the PSP's ledger. - [Retrieve a Transaction Report](https://docs.joinforage.app/reference/get-transaction-report.md): A `GET` request to `/reporting/transactions/` retrieves a [Transaction Log](ref:reports#transaction-reports). On success, the API returns a list of transactions created between the provided `start_date` and `end_date`. Forage defines a transaction as any financial operation that triggers a flow of funds, including both EBT purchases and EBT refunds. A Transaction Report is useful for reconciling your accounting books against the Forage ledger. The fee field can help finance teams reconcile the payouts received from Forage. > ⚠️ Credit/Debit Settlement Handled By PSP > > Credit and debit card transactions are included in the report if the transaction occurred via a Fully Hosted integration, but Forage is never involved in the settlement flow for credit/debit. That falls to the [credit/debit PSP](doc:ebt-online-101#creditdebit-payment-service-provider-psp), so balance your credit/debit accounting against the PSP's ledger. - [Reports](https://docs.joinforage.app/reference/reports.md): You can use the Forage API to retrieve data about your EBT SNAP business - [Changelog](https://docs.joinforage.app/reference/changelog.md): This page lists all the changes for each supported version of the Forage API. Versions are named by their release date in the YYYY-MM-DD format. - [Errors](https://docs.joinforage.app/reference/errors.md): Reference documentation for Forage Payments API errors - [Idempotency](https://docs.joinforage.app/reference/idempotency.md): An idempotency key is a unique string identifier, provided by your app, that Forage can use to recognize retries of the same request. - [Introduction](https://docs.joinforage.app/reference/introduction.md): Get started with the Forage Payments API for accepting EBT SNAP online - [Request Limits](https://docs.joinforage.app/reference/request-limits.md): Learn about how Forage rate limits the Payments API - [Versioning](https://docs.joinforage.app/reference/version-history.md): Reference documentation for the Forage Payments API for accepting EBT SNAP online. Read about the different API versions and their features for processing EBT SNAP online. - [Create a Custom Payment Capture Session](https://docs.joinforage.app/reference/create-capture-session.md): 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](ref: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](ref:create-order-payment), or to check the status of the `Order` via a `GET` to [`/orders/{order_ref}/`](ref: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}/`](ref: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. - [Create a Custom Balance Check Session](https://docs.joinforage.app/reference/create-custom-balance-check-session.md): > ⚠️ FNS Requirements > > FNS prohibits balance inquiries on sites and apps that offer guest checkout. Do not use this endpoint if your customers can opt for guest checkout. > > If guest checkout is not an option, then it's up to you whether or not to add a balance inquiry feature. No FNS regulations apply. A `POST` request to `/balance_sessions/` initiates a `Session` of the Custom Balance Check Forage UI. Pass the Forage [`PaymentMethod`](ref:payment-methods) `ref`, the hashed reference ID that represents the EBT Card, as the `payment_method` param in the request body. The response payload represents the [Custom Balance Check `Session`](ref:forage-sessions#custom-balance-check-session). The `redirect_url` value is the URL that launches the front-end, customer-facing Forage UI. Point a customer to this URL to enter their PIN to perform a secure balance inquiry. If PIN entry is successful, then Forage points the customer to the `success_redirect_url` specified in the request body. Forage directs them to the `cancel_redirect_url` if they cancel the balance inquiry via the Forage UI. > 📘 Retrieve Customer EBT Card Balance > > After a customer completes the Forage UI and is pointed to your `success_redirect_url`, send a `GET` to [`/api/payment_methods/{payment_method_ref}/`](ref:get-payment-method) and inspect the `balance` field of the response to retrieve their EBT Card balance. See these guide for additional information: - [How Custom integrations work (Check the balance of an EBT account)](doc:custom#check-the-balance-of-an-ebt-account) - [Custom Quickstart](doc:custom-quickstart) - [Custom Balance Check `Session` payload](ref:forage-sessions#custom-balance-check-session) - [Retrieve a Custom Balance Check Session](https://docs.joinforage.app/reference/view-balance-session.md): > ⚠️ Check EBT Card Balance > > This endpoint does not return a customer's EBT Card balance. If you're looking for a customer's EBT Card balance, then send a `GET` to [`/api/payment_methods/{payment_method_ref}`](ref:get-payment-method), and inspect the `balance` response field. A `GET` request to `/balance_sessions/` retrieves the properties of a Custom Balance Check Session. Use this endpoint to inspect a `Session`'s `success_redirect_url` and `cancel_redirect_url` values. See these guides for additional information: - [Create a Custom Balance Check `Session`](ref:create-custom-balance-check-session) - [Custom Balance Check `Session` payload](ref:forage-sessions#custom-balance-check-session) - [How Custom integrations work (Check the balance of an EBT account)](doc:custom#check-the-balance-of-an-ebt-account) - [Custom Quickstart](doc:custom-quickstart) - [Create a Fully Hosted Session](https://docs.joinforage.app/reference/create-session.md): 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) - [Cancel an OrderPayment](https://docs.joinforage.app/reference/cancel-an-order-payment.md): > ⚠️ `OrderPayment`` Updates Must Be Server-Side > > To keep your app secure, requests to cancel an OrderPayment should only be generated on the server-side. A `POST` request to `/orders/{order_ref}/payments/{payment_ref}/cancel/` cancels an existing `OrderPayment`. An `OrderPayment` can only be cancelled if its `status` is `requires_confirmation` or `failed`. Because only payments in these unsuccessful states can be canceled, this endpoint has no financial side effects. On success, the API responds with the original `OrderPayment` object. - [Retrieve all OrderPayments for an Order](https://docs.joinforage.app/reference/get-all-payments.md): A `GET` request to `/orders/{order_ref}/payments/` retrieves all `OrderPayments` associated with the provided `order_ref`. On success, the API responds with an array of `OrderPayments`. - [Retrieve an OrderPayment](https://docs.joinforage.app/reference/get-an-order-payment.md): A `GET` request to `/orders/{order_ref}/payments/{payment_ref}/` retrieves the specified [`OrderPayment`](ref:order-payments). - [Update an OrderPayment](https://docs.joinforage.app/reference/patch-update-an-order-payment.md): > ⚠️ Update `OrderPayment` Server-Side Only > > To keep your app secure, requests to update an `OrderPayment` should only be generated on the server-side. A `PATCH` request to `/orders/{order_ref}/payments/{payment_ref}/` updates an existing Forage `OrderPayment`. On success, the API responds with the updated [OrderPayment](ref:order-payments) object. The `status` property of the `OrderPayment` determines what data can be updated. If the `status` is `processing`, `canceled`, or `succeeded`, then only the following `Payment` fields can be modified: - `metadata` - `external_order_id` During these statuses, Forage ignores attempts to update other `OrderPayment` fields. - [Create refunds for specific products in an Order](https://docs.joinforage.app/reference/create-refunds-by-product.md): > ⚠️ Product Refunds Must Be Server-Side > > To keep your app secure, requests to refund specific products should only be generated on the server-side. A `POST` request to `/orders/{order_ref}/refund_by_product/` creates refunds for specific products in an `Order`. It tells Forage's servers to create `OrderRefund` objects for the specified products and refund the appropriate amounts to their original payment methods. This request has immediate financial side effects. On success, the API responds with an array of refund objects that represent the transactions and a `201` HTTP status code. ### HTTP STATUS 201 This endpoint always returns a `201`, even if some refund attempts fail, because Forage always creates refund objects to preserve a record of the attempted transactions. To make sure that the refunds were successful, check that the `status` of each refund is `succeeded`. Send periodic `GET` requests to `/orders/{order_ref}/refunds/{refund_ref}/` to retrieve the updated objects. If the status is `failed`, then inspect the `last_processing_error` field of the response object for information about the error. > 📘 Webhooks For Refund Status Updates > > Forage sends a `REFUND_STATUS_UPDATED` webhook when the status of a refund changes. Check out the [guide to Forage webhooks](doc:configure-webhooks#refund_status_updated) for instructions on how to listen for the event. - [Retrieve all OrderRefunds for an Order](https://docs.joinforage.app/reference/get-all-order-refunds.md): A `GET` request to `/orders/{order_ref}/refunds/` retrieves all `OrderRefunds` associated with the provided `order_ref`. On success, the API responds with an array of [`OrderRefunds`](ref:order-refunds#orderrefund-object). - [Retrieve an OrderRefund](https://docs.joinforage.app/reference/get-an-order-refund.md): A `GET` request to `/orders/{order_ref}/refunds/{refund_ref}/` retrieves the specified refund for a given order. On success, the API responds with the [`OrderRefund`](ref:order-refunds#orderrefund-object). Use this endpoint to inspect the outcome of an order refund, including updated `receipt` information to display to the customer. - [Create a refund for an entire Order](https://docs.joinforage.app/reference/refund-entire-order.md): > ⚠️ Refunding Entire Orders Must Be Server-Side > > To keep your app secure, requests to refund an entire Order should only be generated on the server-side. A `POST` request to `/orders/{order_ref}/refund_all/` refunds an entire `Order`. It tells Forage's servers to create an `OrderRefund` for every associated `OrderPayment`, and to refund all charges to their original payment methods, net any already processed refunds. This request has immediate financial side effects. On success, the API responds with the original [`Order`](ref:orders). The `refunds` field details a list of reference hashes, `refund_refs`, for all of the `OrderRefunds` that Forage created as part of the refund process. If there are any `OrderRefunds` still processing when you send the `POST`, then the API returns a `400` until those refunds have resolved. To retrieve information about a particular `OrderRefund` in the list, send a `GET` to [`/orders/{order_ref}/refunds/{refund_ref}/`](ref:get-an-order-refund). > ⚠️ Retrieving Refund Receipt Info > > This endpoint does not return `receipt` information. > > To retrieve transaction information to display to a customer, send periodic `GET` requests to `/orders/{order_ref}/refunds/{refund_ref}/` for every`OrderRefund` returned in the `refunds` field until the status of each is `succeeded`. Then, confirm that the `receipt.balance.updated` timestamp is no longer changing and retrieve the latest balance. > 📘 Webhooks For Refund Status Updates > > Forage sends a `REFUND_STATUS_UPDATED` webhook when the status of a refund changes. Check out the [guide to Forage webhooks](doc:configure-webhooks#refund_status_updated) for instructions on how to listen for the event. - [Create a refund for part of an Order](https://docs.joinforage.app/reference/refund-partial-order.md): > ⚠️ Partial Refunds Must Be Server-Side > > To keep your app secure, requests to refund part of an Order should only be generated on the server-side. > ⚠️ API Version Requirements > > You must use Forage version `2024-01-08` or higher for this endpoint to return populated `receipt` data. Earlier versions return the receipt value as null, so to retrieve the data you need to send `GET` requests to `/orders/{order_ref}/refunds/{refund_ref}/` until the status of the refund is `succeeded`. A `POST` request to `/orders/{order_ref}/refunds/` refunds part of an `Order`. It tells Forage's servers to refund a specific `amount` of a single `OrderPayment` associated with the `Order`. This request has immediate financial side effects. On success, the API responds with an [`OrderRefund`](ref:order-refunds) that represents the transaction and a `201` HTTP status code. ### HTTP STATUS 201 This endpoint always returns a `201`, even if the refund attempt fails, because Forage always creates an `OrderRefund` to preserve a record of the attempted transaction. To make sure that the refund was successful, check that the `status` is `succeeded`. Send periodic `GET` requests to `/orders/{order_ref}/refunds/{refund_ref}/` to retrieve the updated object. If the status is `failed`, then inspect the `last_processing_error` field of the response object for information about the error. - [Cancel an Order](https://docs.joinforage.app/reference/cancel-order.md): A `POST` request to `/orders/{order_ref}/cancel/` cancels an existing `Order`. An `Order` can only be canceled if its `status` is `draft`. Cancel an `Order` to prevent it from being submitted for capture in the future, while still maintaining a record of the `Order` on Forage's server. On success, the API responds with the canceled `Order` object. Check the [Forage Errors reference](ref:errors) for a comprehensive list of error codes. - [Retrieve an Order](https://docs.joinforage.app/reference/get-order.md): A `GET` request to `/orders/{order_ref}/` retrieves the specified [`Order` object](ref:orders#order-object). The `order_ref` is the `ref` value that Forage returns in response to the request that created the order's parent [`Session`](ref:forage-sessions). You can use this endpoint to request the transaction outcome from Forage after a customer completes a Fully Hosted or Custom Session. - [Update an Order](https://docs.joinforage.app/reference/update-order.md): A `PATCH` request to `/orders/{order_ref}/` modifies the indicated [`Order` object](ref:orders#order-object). The `order_ref` is the `ref` value that Forage returns in response to the request that created the `Order`'s parent [`Session`](ref:forage-sessions). On success, the API responds with the updated `Order`. To modify payments associated with an `Order`, send a request to [Update an `OrderPayment`](ref:update-an-order-payment) instead. - [Create a PaymentRefund](https://docs.joinforage.app/reference/create-payment-refund.md): > ⚠️ Refund Requests Must Be Server-Side > > To keep your app secure, requests to create a PaymentRefund should only be generated on the server-side. > ⚠️ API Version Requirements > > You must use Forage version `2024-01-08` or higher for this endpoint to return populated `receipt` data. Earlier versions return the `receipt` value as `null`, so to retrieve the data you need to send `GET` requests to [`/payments/{payment_ref}/refunds/{refund_ref}/`](ref:get-a-payment-refund) until the `status` of the refund is `succeeded`. A `POST` request to `/payments/{payment_ref}/refunds/` tells Forage's servers to refund an existing `Payment` object. Funds are refunded to the originally charged [`PaymentMethod`](ref:payment-methods). On success, Forage automatically begins processing the refund, so this request has immediate financial side effects. The API responds with a Forage `PaymentRefund` object that represents the transaction and an HTTP `201` status code. #### Deferred refunds ForageTerminalSDK integrations use this endpoint to complete **deferred refunds**. Here are the steps: 1. Collect the customer's PIN using Forage's POS SDK. 2. At the appropriate point in your refund workflow, call this endpoint to initiate the refund. 3. If an error occurs (e.g., *an Invalid PIN*), relay the message back to the POS client immediately so the user is notified promptly. #### HTTP `201` HTTP `201` is returned even if the refund attempt fails because Forage creates a `PaymentRefund` object to preserve a record of the refund regardless of the transaction outcome. To confirm that the outcome is a success, check that the `status` of the `PaymentRefund` is `succeeded`. If the status is `failed`, then for Forage version `2024-01-08` or higher inspect the `receipt.message` field of the response for a description of the error. For earlier Forage versions, send a `GET` to [`/payments/{payment_ref}/refunds/`](ref:get-all-payment-refunds) to retrieve updated `receipt` data. - [Retrieve a PaymentRefund for a Payment](https://docs.joinforage.app/reference/get-a-payment-refund.md): A `GET` request to `/payments/{payment_ref}/refunds/{refund_ref}/` retrieves a `PaymentRefund` associated with a `Payment`. Use this endpoint to retrieve updated `receipt` and `balance` information for a `PaymentRefund` after the initial POST request [creates the refund](ref:create-payment-refund). - [Retrieve all PaymentRefunds for a Payment](https://docs.joinforage.app/reference/get-all-payment-refunds.md): A `GET` request to `/payments/{payment_ref}/refunds/` retrieves a list of all `PaymentRefunds` associated with a `Payment`. To inspect a particular `PaymentRefund`, use [`/payments/{payment_ref}/refunds/{refund_ref}/`](ref:get-a-payment-refund). - [Payment Refunds](https://docs.joinforage.app/reference/payment-refunds.md): A `PaymentRefund` represents a refund of an existing `Payment` object. - [Void a PaymentRefund](https://docs.joinforage.app/reference/void-a-refund.md): > ⚠️ POS Terminal Integrations Only > > This endpoint is only relevant to Forage POS Terminal integrations. A `POST` request to `/payments//refunds//void/` reverses a successfully processed `PaymentRefund`. It reinstates the original charge to the customer. On success, the API responds with the `PaymentRefund` object, and the `is_voided` value is `true`. > ⚠️ Post-Void Balance Requires PIN Check > > The `balance` value in the response does not reflect the voided transaction. The returned `balance` amount accounts for the original transaction, before the void. A customer must check their balance via PIN entry to get the post-void balance. - [Authorize a Payment](https://docs.joinforage.app/reference/authorize-a-payment.md): > ⚠️ HSA/FSA Payments Only > > This endpoint can only be used for HSA/FSA payments. A `POST` request to `/payments/{payment_ref}/authorize/` performs an Authorization on an existing [`Payment` object](ref:payments#payment-object). A hold will be placed on the cardholder's account for the `amount` of the payment. This hold will appear on the cardholder's statement as a pending transaction. If `request_partial_authorization` is `true` then the amount authorized may be less then the original payment `amount`. In this case the original `amount` is moved into a field `requested_amount` and the actual amount authorized will be in field `amount`. - [Cancel or Void a Payment](https://docs.joinforage.app/reference/cancel-a-payment.md): A `POST` request to `/payments/{payment_ref}/cancel/` stops an existing [`Payment` object](ref:payments#payment-object) from being submitted for capture in future API calls. For EBT Payments, a `Payment` can only be canceled if its `status` is `requires_confirmation` or `failed`. For HSA/FSA payments, the `Payment` can only be canceled if its `status` is `authorized`. For HSA/FSA payments, this endpoint voids a previous authorization, or prevents future authorization attempts against the `Payment`. A voided authorization will be removed from the cardholder's statements. - [Create a Payment](https://docs.joinforage.app/reference/create-a-payment.md): > ⚠️ Payment Creation Must Be Server-Side > > To keep your app secure, requests to create a Payment should only be generated on the server-side. A `POST` request to `/payments/` tells Forage's servers how much to charge an existing `PaymentMethod`. On success, the API responds with a Forage `Payment` object that represents the one-time charge. You need to pass the `ref` response value to an SDK function to authorize and capture the payment, one of: - Forage JS: [`capturePayment()`](ref:capture-ebt-payment) - Android: [`capturePayment()`](https://android.joinforage.app/forage-android/com.joinforage.forage.android.ecom.services/-forage-s-d-k/capture-payment) - iOS: [`capturePayment()`](https://github.com/teamforage/forage-ios-sdk?tab=readme-ov-file#capture-an-ebt-payment) > 📘 Use `customer_id` When Creating Payments > > Pass `customer_id` in the request to Create a `Payment`. `customer_id` helps Forage's servers more quickly identify and associate the correct customer with the `Payment`. While `customer_id` is not technically a required parameter, if you omit it then the request to create the `Payment` could take longer to process. **It is strongly recommended to pass `customer_id`.** > > Each customer should only have one unique `customer_id`. For example, if you create both a `Payment` 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. > ⚠️ Payments Expire After 30 Minutes > > `Payment` objects expire after 30 minutes. If a `Payment` is not captured or canceled within 30 minutes of when it's created, then it expires. To attempt the transaction again, create a new `Payment`. - [Capture an EBT or HSA/FSA Payment](https://docs.joinforage.app/reference/capture-a-payment.md): > 📘 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. - [Retrieve a Payment](https://docs.joinforage.app/reference/get-payment-details.md): A `GET` request to `/payments/{payment_ref}/` retrieves the specified [`Payment` object](ref:payments#payment-object). Use this endpoint to confirm the `status` of a `Payment`, and/or to retrieve and display the `receipt` data to a customer. - [Payments](https://docs.joinforage.app/reference/payments.md) - [Retrieve all Payments for a merchant order ID](https://docs.joinforage.app/reference/retrieve-all-payments-for-merchant-order-id.md): A `GET` request to `/payments/` that includes the `external_order_id` query param retrieves a list of all of the `Payment`s related to the order. The `external_order_id` corresponds to a merchant or platform's identifier for the order in their own database. Forage does not provide this value. If a customer charges both SNAP and EBT Cash at checkout, then this endpoint could be useful to review the spending breakdown across `Payment` types. **Refund details:** By default, the `refunds` field contains only refund reference strings. Include `with_refunds` to get complete refund information. You can pass it as `&with_refunds` (no `=true` required). - [Capture a Payment during sandbox testing](https://docs.joinforage.app/reference/capture-a-payment-during-sandbox-testing.md): A `POST` request to `/payments/{payment_ref}/capture-sync/` programmatically captures an existing [`Payment` object](ref:payments#payment-object). Use this endpoint to automate sandbox testing. - [Submit a test PIN during sandbox development](https://docs.joinforage.app/reference/submit-pin-during-sandbox-testing.md): > ⚠️ Use For Sandbox Only > > Only use this endpoint during sandbox testing. It cannot be used in production. A `POST` request to `/payments/{payment_ref}/collect_pin_backend/` programmatically associates a test PIN with an existing `Payment` object. Use this endpoint to automate sandbox testing when you're building an integration that [defers payment capture to the server](doc:capture-ebt-payments-server-side). - [Update a Payment](https://docs.joinforage.app/reference/update-a-payment.md): > ⚠️ Update Payment Requests Server-Side > > To keep your app secure, requests to update a `Payment` should only be generated on the server-side. A `PATCH` request to `/payments/{payment_ref}/` updates an existing Forage `Payment`. On success, the API responds with the updated [Payment](ref:payments) object. The `status` property of the `Payment` determines what data can be updated. If the `status` is `processing`, `cancelled`, or `succeeded`, then only the following `Payment` fields can be modified: - `metadata` - `external_order_id` During these statuses, Forage ignores attempts to update other `Payment` fields. > 📘 Required For Server-Side Capture > > You need to use this endpoint if you're building an integration that [defers payment capture to the server](doc:capture-ebt-payments-server-side). - [Void a Payment](https://docs.joinforage.app/reference/void-a-payment-custom-checkout.md): > ⚠️ POS Terminal and HSA/FSA Payments Only > > This endpoint is only relevant to Forage EBT POS Terminal integrations and HSA/FSA payments. > 📘 For EBT Prefer Refunds Over Voids > > In most cases, instead of voiding an EBT `Payment`, [create a `PaymentRefund`](ref:create-payment-refund). > > For EBT `PaymentRefunds` and voided `Payments` have the same impact on settlement, but refunds provide a better paper trail. The refunds API also gives you more granular control over, for example, the fraction of the original `Payment` to refund. A `POST` request to `/payments/{payment_ref}/void/` voids the payment transaction. On success, this endpoint reverses the impacts of the payment on daily net settlement. The API responds with the original [`Payment`](ref:payments) object. > ⚠️ EBT Balance Value Doesn't Reflect Voids > > For EBT payments, the `balance` value in the response does not reflect the voided transaction. The returned `balance` amount accounts for the original transaction, before the void. A customer must check their balance via PIN entry to get the post-void balance. - [Capture an EBT payment](https://docs.joinforage.app/reference/capture-ebt-payment.md) - [Check the balance of an EBT card](https://docs.joinforage.app/reference/check-the-balance-of-an-ebt-card.md) - [Collect an EBT Card PIN for server-side payment capture](https://docs.joinforage.app/reference/collect-an-ebt-card-pin-for-server-side-payment-capture.md) - [Forage Elements](https://docs.joinforage.app/reference/ebt-elements.md) - [Tokenize an EBT Card](https://docs.joinforage.app/reference/store-an-ebt-card.md) - [Tokenize a Payment Sheet](https://docs.joinforage.app/reference/tokenize-a-payment-sheet.md) - [change](https://docs.joinforage.app/reference/change.md) - [Events](https://docs.joinforage.app/reference/events.md) - [ready](https://docs.joinforage.app/reference/ready.md) - [Forage JS Errors](https://docs.joinforage.app/reference/forage-js-errors.md) - [Input Validation](https://docs.joinforage.app/reference/input-validation.md) - [Introduction](https://docs.joinforage.app/reference/js-sdk-reference.md) - [Initialize Forage JS](https://docs.joinforage.app/reference/initialize-forage-js.md): `Forage(ForageConfig)` - [Set up](https://docs.joinforage.app/reference/set-up.md) - [clear()](https://docs.joinforage.app/reference/clear.md): `element.clear()` - [destroy()](https://docs.joinforage.app/reference/destroy.md): `element.destroy()` - [Methods](https://docs.joinforage.app/reference/methods.md) - [mount()](https://docs.joinforage.app/reference/mount.md): `element.mount(htmlElementId)` - [on()](https://docs.joinforage.app/reference/on.md): `element.on(elementEvent, handler)`