Sign in

v1

latestOpenAPI 3.0.02026-07-244352379.2 KB
Order Refunds

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.

get/api/orders/{order_ref}/refunds/

Headers

Authorizationstring required

An OAuth 2.0 authentication token that validates the request. Send a POST to the /o/token/ endpoint to generate an authentication token. Pass the token in this header after the word Bearer and a whitespace, for example Bearer <api_key>.

Merchant-Accountstring required

A unique merchant ID that Forage provides during onboarding, as in 123ab45c67. The Merchant ID can be found in the Forage sandbox or production dashboard.

API-Versionstring

The Forage version, represented as a string with the format of a YYYY-MM-DD date.

If not specified in the request header, then the version defaults to the value set in the Forage dashboard.

Response

OK - Success

paymentstring required

A unique reference hash for the Forage OrderPayment to be refunded, returned when the OrderPayment was created.

amountnumber required

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 0.01.

reasonstring required

A string that describes why the refund is happening.

metadataMetadataObject required

A required object containing merchant-defined key-value pairs to provide additional context for the payment.

Merchants 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.

Pass an empty object ({}) if no additional information is available.

⚠️ Personally Identifiable Information

Do not include personally identifiable information (PII) such as names, emails, or payment details.

merchant_fixed_settlementnumber

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_settlementnumber

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_idstring

A unique identifier for the order as created by the merchant or platform (not Forage).

When 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.

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.

refstring

A unique reference hash for the OrderRefund.

orderstring

The unique reference hash for the parent Forage Order.

funding_type'benefit' | 'credit_tpp' | 'ebt_snap' | 'ebt_cash'

A string that represents the type of tender. One of:

  • benefit
  • credit_tpp
  • ebt_snap
  • ebt_cash
status'canceled' | 'failed' | 'processing' | 'succeeded'

The status of the OrderRefund. One of:

  • canceled: The OrderRefund has been voided and can't be changed.

  • failed: The OrderRefund failed to process. Check the receipt.message field for a description of the error.

  • 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.

  • succeeded: The OrderRefund has been successfully processed and will be included in settlement.

last_processing_errorobject nullable

The code and message values corresponding to the most recent Payments API error. Always null when the Payment is created.

createdstring date-time

A UTC timestamp that indicates when this object was created, represented as an ISO 8601 date-time string.

updatedstring date-time

A UTC timestamp that indicates when this object was last modified, represented as an ISO 8601 date-time string.

tpp_lookup_idstring

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.

Example response

[
  {
    "ref": "45e3f12a90",
    "order": "83b1c754ae",
    "funding_type": "ebt_snap",
    "status": "processing",
    "created": "2021-06-16T00:11:50.000000Z",
    "updated": "2021-06-16T00:11:50.000000Z",
    "receipt": {
      "balance": {
        "id": 12345
      }
    },
    "tpp_lookup_id": "re_3JemUSGfBYJeLEva0af6My64"
  }
]