Forage · Schema

OrderRefundResponse

CompanyPaymentsEBTSNAPEBT CashHSA/FSAFintechGovernment BenefitsGroceryCheckoutFinancial Services

Properties

Name Type Description
payment string 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 string 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. The minimum amount that can be refunded is
reason string A string that describes why the refund is happening.
metadata object
merchant_fixed_settlement string 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 string 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 object
ref string A unique reference hash for the `OrderRefund`.
order string The unique reference hash for the parent Forage `Order`.
funding_type string A string that represents the type of tender. One of: - `benefit` - `credit_payfac` - `credit_tpp` - `ebt_cash` - `ebt_snap` - `wic`
status string The status of the `OrderRefund`. One of: - `canceled`: The `OrderRefund` has been voided and can’t be changed. - `expired`: The `OrderRefund` has expired and can’t be used. - `failed`: The `OrderRefun
last_processing_error objectnull 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.
created string 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.
updated string 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.
receipt object
tpp_lookup_id stringnull 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.
View JSON Schema on GitHub

JSON Schema

forage-order-refund-response-schema.json Raw ↑
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/forage/main/json-schema/forage-order-refund-response-schema.json",
  "title": "OrderRefundResponse",
  "x-generated": "2026-10-14",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/forage-payments-api-openapi.yml#/components/schemas/OrderRefundResponse",
  "allOf": [
    {
      "$ref": "#/$defs/OrderRefundRequest"
    },
    {
      "type": "object",
      "properties": {
        "ref": {
          "type": "string",
          "description": "A unique reference hash for the `OrderRefund`."
        },
        "order": {
          "type": "string",
          "description": "The unique reference hash for the parent Forage `Order`."
        },
        "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"
          ]
        },
        "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"
          ]
        },
        "last_processing_error": {
          "type": [
            "object",
            "null"
          ],
          "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."
        },
        "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."
        },
        "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."
        },
        "receipt": {
          "allOf": [
            {
              "$ref": "#/$defs/ReceiptData"
            }
          ],
          "nullable": true
        },
        "tpp_lookup_id": {
          "type": [
            "string",
            "null"
          ],
          "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"
        }
      },
      "required": [
        "ref",
        "order",
        "funding_type",
        "created",
        "updated",
        "status",
        "amount",
        "metadata"
      ]
    }
  ],
  "$defs": {
    "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."
        },
        "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."
        }
      }
    },
    "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"
    },
    "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": "#/$defs/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": "#/$defs/ExternalOrderIDField"
        }
      },
      "required": [
        "payment",
        "amount",
        "reason",
        "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",
            "null"
          ],
          "format": "currency",
          "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": "#/$defs/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",
            "null"
          ],
          "description": "The terminal transaction sequence number for POS transactions. `null` for online (non-POS) transactions."
        }
      }
    }
  }
}

Work with this as data

Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for schemas

4 MCP tools reach this
  • find_json_schemasBrowse and filter every JSON Schema in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/forage-order-refund-response"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.