---
title: "Refund a Payment"
method: POST
path: "/payments/{id}/refunds"
tags: ["Payments", "Refunds"]
---

# Refund a Payment

`POST /payments/{id}/refunds`

## Request

- Base URL: `https://api.justifi.ai/v1`
- URL: `https://api.justifi.ai/v1/payments/{id}/refunds`
- Auth: none declared. Required headers: `Idempotency-Key`, `Authorization`
- TypeScript: <https://skmtc.dev/justifi/apis/justifi-api-documentation/docs/payments/:id/refunds/post.ts> (a function with typed inputs; its response is checked against the schema)

Issue a refund for a payment. You may refund the full payment amount or just a portion. When refunding a portion, multiple refunds are supported up until the full payment amount has been refunded.

*Note: If the sub account status is not `enabled`, `400` will be returned.*

## Path parameters

- `id` string, uuid, required

## Headers

- `Idempotency-Key` string, uuid, required
- `Authorization` string, required

## Request body

- object
  - `amount` number: amount to refund; must be less than or equal to the `amount_refundable` on the payment
  - `description` string: an optional note about this refund
  - `reason` 'duplicate' | 'fraudulent' | 'customer_request': the reason this refund is being issued
  - `fees` object[]: Array of fee objects to return to the merchant as part of this refund. If omitted, no fees are returned (current behavior preserved). Each fee object specifies: - `type`: The fee type to refund (`processing_fee` or `platform_fee`) - `amount`: Amount to return in cents **Validation:** - The requested amount cannot exceed the `remaining_amount` for that fee type on the original payment - The fee type must exist on the original payment > **CAD Payments:** This parameter is not available for CAD payments. See [Canadian Payments](https://docs.justifi.tech/payments/canadianPayments) for details. See [Enhanced Fee Management](#section/Enhanced-Fee-Management) for full documentation.
    - `type` 'processing_fee' | 'platform_fee', required: The type of fee to refund
    - `amount` integer, required: Amount to refund in cents
  - `metadata` object: any useful information you'd like to store alongside this refund

## Response `201`

Refund was created successfully

- object
  - `id` string, uuid: the object id, also found in the data object
  - `type` string: the object type, or array of objects
  - `data` object: the attributes for the object
    - `id` string: refund unique id
    - `payment_id` string, uuid: the payment for which this refund is being issued
    - `amount` number: the amount of this refund in cents
    - `description` string: an optional note about this refund
    - `reason` 'duplicate' | 'fraudulent' | 'customer_request': the reason this refund is being issued
    - `status` 'pending' | 'succeeded' | 'failed': the status of this refund
    - `metadata` object: any useful information you'd like to store alongside this refund
    - `returned_fees` ReturnedFeeResponse[]: Array of returned fee objects showing the fees returned to the merchant with this refund. Present when fees were specified in the refund request. See [Enhanced Fee Management](https://docs.justifi.tech/api-spec#section/Enhanced-Fee-Management) for full documentation.
      - `id` string, required: Unique identifier for this returned fee
      - `payment_fee_id` string, required: Unique identifier for the original payment fee that was partially or fully returned
      - `type` 'processing_fee' | 'platform_fee', required: The type of fee that was returned: - `processing_fee`: Processing fee returned to merchant - `platform_fee`: Platform fee returned to merchant
      - `returned_amount` integer, required: Amount returned to the merchant in cents
      - `original_amount` integer, required: Original fee amount in cents from the payment
      - `currency` string, required: Currency of the fee amounts
      - `remaining_amount` integer, required: Amount still available for refund on the original payment fee in cents
    - `created_at` string, date-time
    - `updated_at` string, date-time
  - `page_info` unknown

---

[API](https://skmtc.dev/justifi/apis/justifi-api-documentation.md) - [All operations](https://skmtc.dev/justifi/apis/justifi-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/justifi/apis/justifi-api-documentation/revisions/dd9f3fed7e46?raw)