--- updatedAt: 2026-05-07T18:17:26.000Z agentTools: projectIndex: https://docs.joinforage.app/llms.txt --- # Retrieve a Payout Transaction Report 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. # 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": { "/reporting/payouts/{payout_id}/transactions/": { "parameters": [ { "$ref": "#/components/parameters/AuthenticationBearerTokenHeader" }, { "name": "Merchant-Account", "in": "header", "description": "A unique merchant ID that Forage provides during onboarding, as in `123ab45c67`.\n\nIf querying on behalf of a platform that supports multiple merchants, then omitting this header returns platform-wide results. You must indicate a `Merchant-Account` header to retrieve results for a specific merchant on a platform.\n", "schema": { "type": "string" }, "required": false }, { "$ref": "#/components/parameters/APIVersionHeader" }, { "$ref": "#/components/parameters/LimitQueryParam" }, { "$ref": "#/components/parameters/CursorQueryParam" }, { "name": "payout_id", "in": "path", "description": "The unique identifier for the payout, retrieved from a [Payout Report](https://docs.joinforage.app/reference/get-payout-report).", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Reports" ], "summary": "Retrieve a Payout Transaction Report", "x-readme": { "code-samples": [ { "language": "curl", "code": "curl --request GET \\\n --url 'https://api.sandbox.joinforage.app/reporting/payouts/27/transactions/?limit=1&cursor=cJ0xMDIzLZAxLTMxKzIxLTNBMzElM0ExNC40NTUxNjMlMkIwMCUzQTAp' \\\n --header 'Authorization: Bearer ' \\\n --header 'Merchant-Account: ' \\\n --header 'accept: application/json'\n" } ] }, "description": "A `GET` request to `/reporting/payouts/{payout_id}/transactions/` retrieves a [Payout Transaction Report](https://docs.joinforage.app/reference/reports#payout-transaction-reports).\n\nA Payout Transaction Report includes a list of all transactions associated with the provided `payout_id`.\n\nForage defines a transaction as any financial operation that triggers a flow of funds, including both EBT purchases and EBT refunds.\n\n> ⚠️ Credit/Debit Settlement Handled By PSP\n>\n> 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](https://docs.joinforage.app/docs/ebt-online-101#creditdebit-payment-service-provider-psp), so balance your credit/debit accounting against the PSP’s ledger.\n", "operationId": "reporting:transactions_by_payout", "security": [ { "OAuth2": [ "reporting", "internal" ] } ], "responses": { "200": { "$ref": "#/components/responses/PayoutTransactionReport200" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "examples": { "invalid_filters": { "summary": "Invalid Filter", "value": { "path": "/reporting/payouts/{payout_id}/transactions/", "errors": [ { "code": "invalid_filters", "message": "{filter}: required filter is missing", "source": { "resource": "Reports", "ref": "" } } ] } }, "invalid_input_data": { "summary": "Invalid Input Data", "value": { "path": "/reporting/payouts/{payout_id}/transactions/", "errors": [ { "code": "invalid_input_data", "message": "Query parameter missing or incomplete.", "source": { "resource": "Reports", "ref": "{payout_id}" } } ] } }, "invalid_merchant_account": { "summary": "Invalid Merchant Account", "value": { "path": "/reporting/payouts/{payout_id}/transactions/", "errors": [ { "code": "invalid_merchant_account", "message": "Merchant account Merchant ID not valid.", "source": { "resource": "Merchants" } } ] } } } } } }, "401": { "description": "__Unauthorized__", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "examples": { "invalid_token": { "summary": "Invalid Token", "value": { "path": "/reporting/payouts/{payout_id}/transactions/", "errors": [ { "code": "invalid_token", "message": "Incorrect authentication credentials.", "source": { "resource": "Accounts", "ref": "" } } ] } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "examples": { "resource_not_found": { "summary": "Resource Not Found", "value": { "path": "/reporting/payouts/{payout_id}/transactions/", "errors": [ { "code": "resource_not_found", "message": "Payout with ID {payout_id} does not exist for current Merchant with FNS {fns_number}" } ], "source": { "resource": "Reports", "ref": "{payout_id}" } } } } } } }, "429": { "description": "__Too Many Requests__", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "examples": { "too_many_requests": { "summary": "Too Many Requests", "value": { "path": "/reporting/payouts/{payout_id}/transactions/", "errors": [ { "code": "too_many_requests", "message": "Request was throttled, please try again later.", "source": { "resource": "Reports", "ref": "" } } ] } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "examples": { "secure_storage_inaccessible": { "summary": "Secure Storage Inaccessible", "value": { "path": "/reporting/payouts/{payout_id}/transactions/", "errors": [ { "code": "secure_storage_inaccessible", "message": "Temporarily unable to access data in secure storage. Please try again.", "source": { "resource": "Reports", "ref": "" } } ] } }, "unknown_server_error": { "summary": "Unknown Server Error", "value": { "path": "/reporting/payouts/{payout_id}/transactions/", "errors": [ { "code": "unknown_server_error", "message": "Unable to continue", "source": { "resource": "Reports", "ref": "" } } ] } } } } } } } } } }, "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" } } }, "PaginatedReportCommonFields": { "properties": { "next": { "type": "string", "nullable": true, "description": "A URL that you can send a `GET` to in order to retrieve the next set of results. Alternatively, you can retrieve the `cursor` value from the URL and pass it in the body of a new request.\n\nThis value is `null` if there are no more results.\n" }, "previous": { "type": "string", "nullable": true, "description": "A URL that you can send a `GET` to in order to retrieve the previous set of results. Alternatively, you can retrieve the `cursor` value from the URL and pass it in the body of a new request.\n\nThis value is `null` if the response includes the first set of results.\n" } } }, "PayoutTransactionReportResponse": { "allOf": [ { "$ref": "#/components/schemas/PaginatedReportCommonFields" }, { "type": "object", "properties": { "next": { "example": "https://api.sandbox.joinforage.app/reporting/payouts/{payout_id}/transactions/?cursor=cD0yMDIzLTAxLTMxKzIxJTNBMzElM0ExNC40NTUxNjMlMkIwMCUzQTAw&end_date=2021-02-28&start_date=2021-01-31" }, "previous": { "example": null }, "results": { "type": "array", "items": { "type": "object", "properties": { "merchant_id": { "type": "string", "description": "A 10-character unique hash identifying the merchant associated with this transaction. Blank if the settlement reflects a platform instead of a merchant payout.\n", "example": "gxe37pc24y" }, "merchant_group_id": { "type": "string", "nullable": true, "description": "The unique identifier of the merchant group associated with this transaction, provided by Forage.", "example": "3hsk173gs8" }, "corporation_id": { "type": "string", "nullable": true, "description": "The unique identifier of the corporation associated with this transaction, provided by Forage.", "example": "6sjqk816dj" }, "fns_id": { "type": "string", "description": "The FNS number of the merchant that received the payout including this transaction. Blank if the settlement reflects a platform instead of a merchant payout.", "example": "1234567" }, "recorded_date": { "type": "string", "format": "date-time", "description": "The date and time of the transaction, formatted as an [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) string in the UTC timezone.", "example": "2024-11-04T14:00:00Z" }, "payout_issued_date": { "type": "string", "format": "date", "nullable": true, "description": "The timestamp of when the payout was created. (Value only populated for Payout Transaction Reports)" }, "expected_deposit_date": { "type": "string", "format": "date", "nullable": true, "description": "The timestamp of when Forage expects the payout to be deposited. This is typically the payout_issued_date plus one business day, if the ACH method is next-day.\n(Value only populated for Payout Transaction Reports)\n" }, "transaction_type": { "type": "string", "description": "The type of the transaction. Must be one of the following:\n\n- `Purchase`\n- `Purchase_With_Cash_Back`\n- `Refund`\n- `Withdrawal`\n- `Chargeback`\n- `Void_Purchase`\n- `Void_Refund`\n- `Negative_adjustment`\n- `Positive_adjustment`\n- `Balance_Inquiry_Fee`\n- `Refund_Processing_Fee`\n\nSee our [Transaction types guide](https://docs.joinforage.app/docs/transaction-type-and-payment-method#transaction-types) for details on credit/debit flow.\n", "example": "Purchase" }, "payment_method": { "type": "string", "description": "The payment method used for the transaction. Must be one of the following:\n\n- `SNAP`\n- `EBT_Cash`\n- `Credit_Debit`\n- `Payfac_Credit_Debit`\n- `HSA`\n- `FSA`\n\nIf the `transaction_type` is one of the following, `payment_method` will be `\"\"`:\n\n- `Positive_adjustment`\n- `Negative_adjustment`\n- `Balance_Inquiry_Fee`\n- `Refund_Processing_Fee`\n\n_Note:_ `Credit_Debit` and `Payfac_Credit_Debit` are only applicable for transactions in Fully Hosted integrations.\n", "example": "SNAP" }, "transaction_amount": { "type": "string", "format": "decimal", "nullable": true, "description": "The total amount in USD charged, voided, or refunded to the customer.", "example": "24.15" }, "forage_fee": { "type": "string", "format": "decimal", "nullable": true, "description": "The amount of Forage fees applied to the transaction.", "example": "0.34" }, "merchant_net_settlement": { "type": "string", "format": "decimal", "nullable": true, "description": "The net amount sent to the merchant, equal to the sum of purchases minus refunds, chargebacks, fees, and any other deductions.\n\nThis value is `null` if the settlement reflects a platform instead of a merchant payout.\n", "example": "21.29" }, "platform_net_settlement": { "type": "string", "format": "decimal", "nullable": true, "description": "The net amount sent to the platform, if applicable, equal to the sum of purchases minus refunds, chargebacks, fees, and any other deductions.\n\nThis value is `null` if the settlement reflects a merchant payout and no platform was involved.\n", "example": "2.37" }, "order_id": { "type": "string", "description": "A 10-character unique hash identifying the order for Fully Hosted and Custom integrations. Blank for SDK integrations.\n", "example": "a9a7226jm8" }, "external_order_id": { "type": "string", "nullable": true, "description": "The unique identifier of the order as created by the merchant or platform (not Forage). This typically corresponds to an identifier in the merchant or platform's database,\nso it can be used as a reference to look up the transaction.\n", "example": "abc123456" }, "payment_id": { "type": "string", "nullable": true, "description": "A 10-character unique hash identifying the related `Payment` or `OrderPayment`.\n", "example": "mn0yo1orjw" }, "refund_id": { "type": "string", "nullable": true, "description": "A 10-character unique hash identifying the related `Refund` or `OrderRefund`.\n", "example": "56us47lbpo" }, "chargeback_id": { "type": "string", "nullable": true, "description": "A 10-character unique hash identifying the chargeback transaction. Present only when `transaction_type` is `Chargeback`.\n", "example": "luw8sozitr" }, "merchant_payout_id": { "type": "string", "nullable": true, "description": "A 10-character unique hash identifying the merchant payout. Present only in Payout Transaction Reports.\n", "example": "jakqbi64tv" }, "platform_payout_id": { "type": "string", "nullable": true, "description": "A 10-character unique hash identifying the platform payout. Present only if the transaction is part of a platform payout, and only in Payout Transaction Reports.\n", "example": "atn1ulwziv" }, "merchant_destination_account_ref": { "type": "string", "nullable": true, "description": "A 10-character unique hash for the merchant's destination bank account. `null` if settled to a platform account.\n", "example": "c45b20e98a" }, "external_location_id": { "$ref": "#/components/schemas/ExternalLocationIDField" }, "description": { "type": "string", "description": "A description of the transaction, as provided by the merchant or platform when the transaction was created." } } }, "required": [ "merchant_id", "fns_id", "merchant_group_id", "corporation_id", "recorded_date", "payout_issued_date", "expected_deposit_date", "transaction_type", "payment_method", "transaction_amount", "forage_fee", "merchant_net_settlement", "platform_net_settlement", "order_id", "external_order_id", "refund_id", "chargeback_id", "merchant_payout_id", "platform_payout_id", "merchant_destination_account_ref", "description" ] } } } ] }, "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" } }, "responses": { "PayoutTransactionReport200": { "description": "__OK__ - Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutTransactionReportResponse" } } } } }, "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/`](https://docs.joinforage.app/reference/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 `.", "schema": { "type": "string" }, "required": true }, "CursorQueryParam": { "name": "cursor", "in": "query", "description": "The starting point for the `results`, as returned in a previous `/reporting/` request. Find a cursor in the URL returned in the `next` and/or `previous` response values.", "schema": { "type": "string" } }, "LimitQueryParam": { "name": "limit", "in": "query", "description": "The maximum number of objects to include in the `results` array. Not to exceed `1000`. If the limit exceeds `1000`, then Forage returns a `400` error response.\n\nDefaults to `100`.\n", "required": false, "schema": { "type": "integer", "default": 100 } }, "APIVersionHeader": { "name": "API-Version", "in": "header", "description": "The [Forage version](https://docs.joinforage.app/reference/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" } } } } } } } ``` # Sibling pages * [Retrieve an Order Report](https://docs.joinforage.app/reference/get-order-report.md) * [Retrieve a Payout Report](https://docs.joinforage.app/reference/get-payout-report.md) * [Retrieve a Transaction Report](https://docs.joinforage.app/reference/get-transaction-report.md)