Sign in

v1

latestOpenAPI 3.0.02026-07-244352379.2 KB
Order Refunds

Create a refund for part of an Order

⚠️ 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 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.

post/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.

Idempotency-Keystring required

An alphanumeric key that clients can use to identify repeated requests that are dropped in transit. Generate a distinct key for every unique request and only re-use keys for retries.

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.

Request body

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.

Response

Created - 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

{
  "payment": "f587edf124",
  "amount": 25.99,
  "reason": "Order could not be delivered",
  "metadata": {},
  "merchant_fixed_settlement": 5.11,
  "platform_fixed_settlement": 5.11,
  "external_order_id": "1f2ee410-5b47-4130-aec2-40f5eb2108f5",
  "ref": "45e3f12a90",
  "order": "83b1c754ae",
  "merchant": "9000055",
  "funding_type": "ebt_snap",
  "status": "processing",
  "last_processing_error": null,
  "created": "2021-06-16T00:11:50.000000Z-07:00",
  "updated": "2021-06-16T00:11:50.000000Z-07:00",
  "receipt": {
    "ref_number": "45e3f12a90",
    "is_voided": true,
    "snap_amount": "25.99",
    "ebt_cash_amount": "10.99",
    "other_amount": "5.99",
    "sales_tax_applied": "5.16",
    "balance": {
      "snap": "72.94",
      "non_snap": "32.16",
      "updated": "2021-06-16T00:11:50.000000Z-07:00"
    },
    "last_4": "3456",
    "message": "Approved",
    "transaction_type": "Refund",
    "created": "2021-06-16T00:11:50.000000Z-07:00"
  },
  "tpp_lookup_id": "re_3JemUSGfBYJeLEva0af6My64",
  "refund_errors": []
}