---
title: "Create a PaymentRefund"
method: POST
path: "/api/payments/{payment_ref}/refunds/"
tags: ["Payment Refunds"]
---

# Create a PaymentRefund

`POST /api/payments/{payment_ref}/refunds/`

> ⚠️ Refund Requests Must Be Server-Side
>
> To keep your app secure, requests to create a PaymentRefund 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 [`/payments/{payment_ref}/refunds/{refund_ref}/`](https://docs.joinforage.app/reference/get-a-payment-refund) until the `status` of the refund is `succeeded`.

A `POST` request to `/payments/{payment_ref}/refunds/` tells Forage’s servers to refund an existing `Payment` object. Funds are refunded to the originally charged [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods).

On success, Forage automatically begins processing the refund, so this request has immediate financial side effects.

The API responds with a Forage `PaymentRefund` object that represents the transaction and an HTTP `201` status code.

#### Deferred refunds

ForageTerminalSDK integrations use this endpoint to complete **deferred refunds**. Here are the steps:

1. Collect the customer's PIN using Forage’s POS SDK.
2. At the appropriate point in your refund workflow, call this endpoint to initiate the refund.
3. If an error occurs (e.g., *an Invalid PIN*), relay the message back to the POS client immediately so the user is notified promptly.

#### HTTP `201`

HTTP `201` is returned even if the refund attempt fails because Forage creates a `PaymentRefund` object to preserve a record of the refund regardless of the transaction outcome. To confirm that the outcome is a success, check that the `status` of the `PaymentRefund` is `succeeded`.

If the status is `failed`, then for Forage version `2024-01-08` or higher inspect the `receipt.message` field of the response for a description of the error. For earlier Forage versions, send a `GET` to [`/payments/{payment_ref}/refunds/`](https://docs.joinforage.app/reference/get-all-payment-refunds) to retrieve updated `receipt` data.

## Headers

- `Authorization` string, required
- `Merchant-Account` string, required
- `Idempotency-Key` string, required
- `API-Version` string

## Request body

- PaymentRefundRequest — 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.

## Response `201`

__Created__ - Success

- 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__ - The request was not accepted because of an error in the request body or path.
- `401` — Unauthorized
- `404` — Resource Not Found
- `409` — Conflict
- `423` — __Locked__ - The request could not be completed because the target resource is currently locked.
- `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)