---
title: "Retrieve a PaymentRefund for a Payment"
method: GET
path: "/api/payments/{payment_ref}/refunds/{refund_ref}/"
tags: ["Payment Refunds"]
---

# Retrieve a PaymentRefund for a Payment

`GET /api/payments/{payment_ref}/refunds/{refund_ref}/`

A `GET` request to `/payments/{payment_ref}/refunds/{refund_ref}/` retrieves a `PaymentRefund` associated with a `Payment`.

Use this endpoint to retrieve updated `receipt` and `balance` information for a `PaymentRefund` after the initial POST request [creates the refund](https://docs.joinforage.app/reference/create-payment-refund).

## Headers

- `Authorization` string, required

## Response `200`

Successful Refund response.

- PaymentRefundResponse — This object represents a refund of a previously created Payment object. Funds will be refunded to the PaymentMethod originally charged.
  - `amount` number, 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`.
  - `reason` string, required — A string that describes why the `Payment` is to be refunded.
  - `metadata` object, 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_settlement` number — 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` number — 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` string — 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.
  - `pos_terminal` object — ⚠️ This param is required for POS Terminal refunds. It is not supported for online-only. An object that details information about the POS Terminal that processed the payment.
    - `provider_terminal_id` string — A unique string that identifies the POS Terminal.
  - `ref` string — A unique reference hash for the `PaymentRefund`.
  - `payment_ref` string — 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`
  - `created` string, date-time — A UTC timestamp that indicates when the `OrderRefund` was created, represented as an [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string.
  - `updated` string, date-time — A UTC timestamp that indicates when the `OrderRefund` was last modified, represented as an [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) 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_error` object, nullable — The `code` and `message` values corresponding to the most recent [Payments API error](https://docs.joinforage.app/reference/errors#payments-api-errors).
  - `receipt` object — 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.
  - `previous_errors` object[] — An array with information about the error.
    - `code` string — A short string that represents the error.
    - `message` string — A developer-facing message with more details about the error, not to be displayed to customers.
    - `source` object
      - `resource` string — The type of the Forage resource involved in the error.
      - `ref` string — 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` object — Additional details about the error, if applicable.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Resource Not Found
- `409` — Conflict
- `429` — Too Many Requests
- `500` — Internal Server Error
- `503` — Service Unavailable

---

[API](https://skmtc.net/joinforage/apis/forage-payments-api.md) · [All operations](https://skmtc.net/joinforage/apis/forage-payments-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/joinforage/forage-payments-api/versions/4b7212706fae/schema)