---
title: "Refund a payment"
method: POST
path: "/v1/payments/{paymentId}/refund"
tags: ["Payments"]
---

# Refund a payment

`POST /v1/payments/{paymentId}/refund`

Issue a full or partial refund for a paid payment. Requires an idempotency key.

## Path parameters

- `paymentId` string, uuid, required

## Headers

- `X-Idempotency-Key` string, required

## Request body

- RefundPaymentRequest
  - `amount` number — Refund amount. Omit for a full refund.
  - `reason` string — Reason for the refund.

## Response `200`

Refund created.

- object
  - `refund` Refund
    - `id` string, uuid
    - `txId` string
    - `amount` number
    - `reason` string
    - `status` 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'REFUNDED' — Generic transaction status.
    - `processedAt` string, date-time
    - `createdAt` string, date-time

## Other responses

- `400` — Validation error.
- `401` — Missing or invalid authentication token.
- `404` — Resource not found.
- `409` — Idempotency conflict, raised by the idempotency middleware. `IDEMPOTENCY_PAYLOAD_MISMATCH` means the key was already used with a different request body, at any point in the 24-hour window, including by a request still in flight. `IDEMPOTENCY_CONFLICT` means a request with the same key and the same body is still being processed. Both use the **flat** envelope: `error` is the HTTP reason phrase and the machine-readable code is the top-level `code`. Note that `IDEMPOTENCY_CONFLICT` raised later by the withdrawal service on an idempotency-key collision uses the nested `Error` envelope instead.

## Changes

- **2026-08-27** `9d4ba1cc037c` — 1 breaking, 3 warning, 3 info
  - the `error` response's property type changed from `object` to `string` for status `409`
  - removed the optional property `error/code` from the response with the `409` status
  - removed the optional property `error/details` from the response with the `409` status
  - removed the optional property `error/message` from the response with the `409` status
  - …3 more
- **2026-04-14** `c75657100757` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/yuvexpay/apis/yuvexpay-api/changes/v1/payments/:paymentId/refund/post.md)

---

[API](https://skmtc.dev/yuvexpay/apis/yuvexpay-api.md) · [All operations](https://skmtc.dev/yuvexpay/apis/yuvexpay-api/llms.txt) · [OpenAPI document](https://skmtc.dev/yuvexpay/apis/yuvexpay-api/revisions/9d4ba1cc037c?raw)