--- updatedAt: 2026-05-07T18:17:26.000Z agentTools: projectIndex: https://docs.joinforage.app/llms.txt --- # Retrieve all OrderRefunds for an Order 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). # 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/orders/{order_ref}/refunds/": { "parameters": [ { "name": "order_ref", "in": "path", "description": "A unique reference hash for the Forage `Order` object, returned when the order’s parent [`Session`](https://docs.joinforage.app/reference/forage-sessions) was created.", "required": true, "schema": { "type": "string" } } ], "get": { "parameters": [ { "$ref": "#/components/parameters/AuthenticationBearerTokenHeader" }, { "$ref": "#/components/parameters/MerchantAccountHeader" }, { "$ref": "#/components/parameters/APIVersionHeader" } ], "tags": [ "Order Refunds" ], "summary": "Retrieve all OrderRefunds for an Order", "x-readme": { "code-samples": [ { "language": "curl", "code": "curl --request GET \\\n --url https://api.sandbox.joinforage.app/api/orders//refunds/ \\\n --header 'Authorization: Bearer ' \\\n --header 'Merchant-Account: ' \\\n --header 'accept: application/json'\n" } ] }, "description": "A `GET` request to `/orders/{order_ref}/refunds/` retrieves all `OrderRefunds` associated with the provided `order_ref`.\n\nOn success, the API responds with an array of [`OrderRefunds`](https://docs.joinforage.app/reference/order-refunds#orderrefund-object).\n", "operationId": "Get all order refunds", "security": [ { "OAuth2": [ "internal", "hosted_checkout", "pinpad_only" ] } ], "responses": { "200": { "description": "__OK__ - Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrderRefundResponse" } } } } }, "400": { "description": "__Bad request__ - The request was not accepted because of an error in the request body or path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "examples": { "invalid_input_data": { "summary": "Invalid Input Data", "value": { "path": "/api/orders/{order_ref}/refunds/", "errors": [ { "code": "invalid_input_data", "message": "Query parameter missing or incomplete.", "source": { "resource": "Orders", "ref": "{order_ref}" } } ] } }, "invalid_merchant_account": { "summary": "Invalid Merchant Account", "value": { "path": "/api/orders/{order_ref}/refunds/", "errors": [ { "code": "invalid_merchant_account", "message": "Merchant account Merchant ID not valid.", "source": { "resource": "Merchants" } } ] } }, "missing_merchant_account": { "summary": "Missing Merchant Account", "value": { "path": "/api/orders/{order_ref}/refunds/", "errors": [ { "code": "missing_merchant_account", "message": "No merchant account was provided.", "source": { "resource": "Merchants" } } ] } }, "unknown_fields_error": { "summary": "Unknown Fields Error", "value": { "path": "/api/orders/{order_ref}/refunds/", "errors": [ { "code": "unknown_fields_error", "message": "Unknown field(s) provided: {unknown_fields}", "source": { "resource": "Orders" } } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "examples": { "expired_session_token": { "summary": "Expired Session Token", "value": { "path": "/api/orders/{order_ref}/refunds/", "errors": [ { "code": "expired_session_token", "message": "This token has expired", "source": { "resource": "Session_Token" } } ] } }, "invalid_token": { "summary": "Invalid Token", "value": { "path": "/api/orders/{order_ref}/refunds/", "errors": [ { "code": "invalid_token", "message": "Incorrect authentication credentials.", "source": { "resource": "Accounts", "ref": "" } } ] } } } } } }, "404": { "description": "__Not Found__ - The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "example": { "path": "/api/orders/{order_ref}/refunds/", "errors": [ { "code": "resource_not_found", "message": "Order with ref {order_ref} does not exist for current Merchant with FNS {fns_number}", "source": { "resource": "Orders", "ref": "{order_ref}" } } ] } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "examples": { "too_many_requests": { "summary": "Too Many Requests", "value": { "path": "/api/orders/{order_ref}/refunds/", "errors": [ { "code": "too_many_requests", "message": "Request was throttled, please try again later.", "source": { "resource": "Orders", "ref": "{order_ref}" } } ] } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseObject" }, "examples": { "unknown_server_error": { "summary": "Unknown Server Error", "value": { "path": "/api/orders/{order_ref}/refunds/", "errors": [ { "code": "unknown_server_error", "message": "Unknown exception from EBT network", "source": { "resource": "Unknown" } } ] } } } } } } } } } }, "components": { "schemas": { "ErrorsArray": { "type": "array", "description": "An array with information about the error.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "A short string that represents the error." }, "message": { "type": "string", "description": "A developer-facing message with more details about the error, not to be displayed to customers." }, "source": { "type": "object", "properties": { "resource": { "type": "string", "description": "The type of the Forage resource involved in the error." }, "ref": { "type": "string", "description": "If applicable, the ten character reference hash of the Forage resource that caused the error. An empty string if no specific individual resource was involved." } } }, "details": { "type": "object", "description": "Additional details about the error, if applicable." } } }, "example": [] }, "ErrorResponseObject": { "type": "object", "description": "An object that includes details about the error.", "properties": { "path": { "type": "string", "description": "The requested endpoint." }, "errors": { "$ref": "#/components/schemas/ErrorsArray" } } }, "BalanceResponse": { "type": "object", "description": "An object that represents an EBT cardholder's account balance.", "properties": { "id": { "type": "integer", "description": "The unique identifier for the balance record.", "example": 12345 }, "snap": { "type": "string", "format": "currency", "description": "The available SNAP balance in USD on the customer’s EBT Card, represented as a numeric string." }, "non_snap": { "type": "string", "format": "currency", "description": "The available EBT Cash balance in USD on the customer's EBT Card, represented as a numeric string." }, "updated": { "type": "string", "format": "date-time", "description": "A UTC timestamp that indicates when the funds in the account last changed, represented as an [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string." }, "sequence_number": { "type": "string", "description": "A transaction number for this `PaymentMethod`'s most recent balance check. Returned only for POS Terminal transactions; omitted from online merchant balance checks." } } }, "OrderRefundRequest": { "type": "object", "description": "This object represents an order refund. It is associated with a previously created OrderPayment object. Funds will be refunded to the PaymentMethod originally charged.", "properties": { "payment": { "type": "string", "description": "A unique reference hash for the Forage `OrderPayment` to be refunded, returned when the [`OrderPayment` was created](https://docs.joinforage.app/reference/create-order-payment)." }, "amount": { "type": "string", "format": "decimal", "description": "The amount to be refunded in USD. Does not need to equal the `amount` field of the `OrderPayment`, if a partial refund. Precision is supported to the penny.\n\nThe minimum amount that can be refunded is `0.01`.\n" }, "reason": { "type": "string", "description": "A string that describes why the refund is happening." }, "metadata": { "$ref": "#/components/schemas/MetadataObject" }, "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." }, "platform_fixed_settlement": { "type": "string", "format": "decimal", "description": "The fixed amount in USD that should be restored to the platform from EBT Cash payments prior to splitting by the `platform_fee`. Precision is supported to the penny." }, "external_order_id": { "$ref": "#/components/schemas/ExternalOrderIDField" } }, "required": [ "payment", "amount", "reason", "metadata" ] }, "OrderRefundResponse": { "allOf": [ { "$ref": "#/components/schemas/OrderRefundRequest" }, { "type": "object", "properties": { "ref": { "type": "string", "description": "A unique reference hash for the `OrderRefund`.", "example": "45e3f12a90" }, "order": { "type": "string", "description": "The unique reference hash for the parent Forage `Order`.", "example": "83b1c754ae" }, "funding_type": { "type": "string", "description": "A string that represents the type of tender. One of:\n\n- `benefit`\n- `credit_payfac`\n- `credit_tpp`\n- `ebt_cash`\n- `ebt_snap`\n- `wic`\n", "enum": [ "benefit", "credit_payfac", "credit_tpp", "ebt_snap", "ebt_cash", "wic" ], "example": "ebt_snap" }, "status": { "type": "string", "description": "The status of the `OrderRefund`. One of:\n\n- `canceled`: The `OrderRefund` has been voided and can’t be changed.\n\n- `expired`: The `OrderRefund` has expired and can’t be used.\n\n- `failed`: The `OrderRefund` failed to process. Check the `receipt.message` field for a description of the error.\n\n- `processing`: The outcome of the `OrderRefund` is pending, and the refund can’t be modified. _This status is not returned if you’re using Forage version `2024-01-08` or higher._\n\n- `requires_confirmation`: The `OrderRefund` requires confirmation before it can be processed. Contact Forage support to confirm this refund.\n\n- `succeeded`: The `OrderRefund` has been successfully processed and will be included in settlement.\n", "enum": [ "canceled", "expired", "failed", "processing", "requires_confirmation", "succeeded" ], "example": "processing" }, "last_processing_error": { "type": "object", "nullable": true, "description": "The `code` and `message` values corresponding to the most recent [Payments API error](https://docs.joinforage.app/reference/errors#payments-api-errors). Always `null` when the `Payment` is created.", "example": null }, "created": { "type": "string", "format": "date-time", "description": "A UTC timestamp that indicates when this object was created, represented as an [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string.", "example": "2021-06-16T00:11:50.000000Z" }, "updated": { "type": "string", "format": "date-time", "description": "A UTC timestamp that indicates when this object was last modified, represented as an [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string.", "example": "2021-06-16T00:11:50.000000Z" }, "receipt": { "allOf": [ { "$ref": "#/components/schemas/ReceiptData" } ], "nullable": true }, "tpp_lookup_id": { "type": "string", "nullable": true, "description": "The unique identifier from the relevant credit TPP or null for EBT refunds. For Stripe integrations, this is the id of the Refund object on Stripe's backend.\n", "example": "re_3JemUSGfBYJeLEva0af6My64" } }, "required": [ "ref", "order", "funding_type", "created", "updated", "status", "amount", "metadata" ] } ] }, "ReceiptData": { "type": "object", "description": "Most of the information that you're required to display to the customer, according to FNS regulations.\n\nThis field is `null` if the data that populates the receipt is not yet available.\n\nThe total amount paid by the customer is `snap_amount` + `ebt_cash_amount` + `other_amount`. This amount will be settled with the merchant after applying Forage's fees.\n", "properties": { "ref_number": { "type": "string", "description": "A unique reference hash for the Forage `Order`, `Payment`, or `Refund` associated with this receipt.\n\nNote: `receipt.ref_number` equals `ref`.\n", "default": "45e3f12a90" }, "is_voided": { "type": "boolean", "description": "Whether the transaction associated with this receipt has been voided. If `false`, then the transaction finished processing as expected. If `true`, then the transaction was reversed." }, "snap_amount": { "type": "string", "description": "The USD amount charged/refunded to the SNAP balance of the EBT Card, represented as a numeric string.", "default": "25.99" }, "ebt_cash_amount": { "type": "string", "format": "currency", "description": "The USD amount charged/refunded to the EBT Cash balance of the EBT Card, represented as a numeric string.", "default": "10.99" }, "cash_back_amount": { "type": "string", "format": "currency", "nullable": true, "description": "The USD amount of cash back given to the customer, represented as a numeric string.", "default": "0.00" }, "other_amount": { "type": "string", "format": "currency", "description": "The USD amount charged/refunded to any payment method that is not an EBT Card, represented as a numeric string.", "default": "5.99" }, "sales_tax_applied": { "type": "string", "format": "currency", "description": "The USD amount of taxes charged to the customer’s non-EBT payment instrument, represented as a numeric string.", "default": "5.16" }, "balance": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/BalanceResponse" } ] }, "last_4": { "type": "string", "description": "The last four digits of the EBT Card number.", "default": "3456" }, "message": { "type": "string", "description": "A message from the EBT payment network that must be displayed to the EBT cardholder.", "default": "Approved" }, "transaction_type": { "type": "string", "enum": [ "Order", "Refund", "Payment" ], "description": "A constant string that is used to identify the transaction type associated with the receipt.\n", "default": "Refund" }, "created": { "type": "string", "format": "date-time", "description": "A UTC timestamp of when the Forage transaction object was created, represented as an [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string.", "default": "2021-06-16T00:11:50.000000Z" }, "sequence_number": { "type": "string", "nullable": true, "description": "The terminal transaction sequence number for POS transactions. `null` for online (non-POS) transactions." } } }, "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" }, "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" } }, "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 }, "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 }, "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 * [Create a refund for an entire Order](https://docs.joinforage.app/reference/refund-entire-order.md) * [Create refunds for specific products in an Order](https://docs.joinforage.app/reference/create-refunds-by-product.md) * [Create a refund for part of an Order](https://docs.joinforage.app/reference/refund-partial-order.md) * [Retrieve an OrderRefund](https://docs.joinforage.app/reference/get-an-order-refund.md)