Sign in

v1

latestOpenAPI 3.0.02026-07-244352379.2 KB
Payment Refunds

Retrieve all PaymentRefunds for a Payment

A GET request to /payments/{payment_ref}/refunds/ retrieves a list of all PaymentRefunds associated with a Payment.

To inspect a particular PaymentRefund, use /payments/{payment_ref}/refunds/{refund_ref}/.

get/api/payments/{payment_ref}/refunds/

Headers

Authorizationstring required

An OAuth 2.0 bearer token that validates the request. You can use either a short-lived session token if the request is coming from the front-end, or an authentication token for server-side requests. 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

amountnumber required

A positive decimal number that represents how much of the Payment to refund in USD. If a partial refund, then this value does not need to equal the amount field of the original Payment. Precision is supported to the penny.

The minimum amount that can be refunded is 0.01.

reasonstring required

A string that describes why the Payment is to be refunded.

metadataobject 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 PaymentRefund.

payment_refstring

The unique reference hash for the Payment to be refunded, as passed in the path params of the request.

funding_type'ebt_snap' | 'ebt_cash' | 'credit_tpp' | 'credit_payfac'

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

  • benefit
  • credit_tpp
  • credit_payfac
  • ebt_cash
  • ebt_snap
createdstring date-time

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

updatedstring date-time

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

status'canceled' | 'failed' | 'processing' | 'succeeded'

The status of the refund. One of:

  • canceled: The PaymentRefund object can't be used.
  • failed: Check receipt.message for a description of the error.
  • processing: The outcome of the refund is pending. This status is not returned if you’re using Forage version 2024-01-08 or higher.
  • succeeded: The refund has been successfully processed and will be included in settlement. It can't be changed.
last_processing_errorobject nullable

The code and message values corresponding to the most recent Payments API error.

receiptobject

Most of the information that you're required to display to the customer, according to FNS regulations.

This field is null if the data that populates the receipt is not yet available.

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

Example response

[
  {
    "merchant_fixed_settlement": 5.11,
    "platform_fixed_settlement": 5.11,
    "pos_terminal": {
      "provider_terminal_id": "1234"
    },
    "ref": "45e3f12a90",
    "payment_ref": "b873fe62dc",
    "funding_type": "ebt_snap",
    "created": "2021-06-16T00:11:50.000000Z",
    "updated": "2021-06-16T00:11:50.000000Z",
    "status": "succeeded",
    "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"
    },
    "previous_errors": []
  }
]