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

# Refund a payment

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

## Request

- Base URL: `https://api.yuvexpay.com`
- URL: `https://api.yuvexpay.com/v1/payments/{paymentId}/refund`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/yuvexpay/apis/yuvexpay-api/docs/v1/payments/:paymentId/refund/post.ts> (a function with typed inputs; its response is checked against the schema)

Issue a full or partial refund for a paid payment. Requires an idempotency key. A payment can be refunded once, fully or partially: after a partial refund a new refund is rejected with `REFUND_ALREADY_PERFORMED`, and after a full refund with `ALREADY_REFUNDED`. While a refund is being processed, a new one is rejected with `400 REFUND_IN_PROGRESS`. A partial refund additionally requires a settled payment and a processing route that supports partial refunds; otherwise it is rejected with `PARTIAL_REFUND_NOT_SUPPORTED`. When the payment carries splits, the refund is apportioned: every party is debited in proportion to what it received, including the originating company, and partial refunds use the same proportions. `INSUFFICIENT_BALANCE_FOR_REFUND` is evaluated against the originating company's share only — a recipient that has already withdrawn its share goes negative instead of blocking the refund, and the shortfall is never moved onto the originating company. When the refund takes the counted volume of your verified CPF or CNPJ below a rewards prize that YuvexPay approved for it, the processing fee is not returned: your balance is debited the full amount returned to the payer, and the kept fee, debited from the originating company only, can take the available balance negative. A `FREE` payment was never charged and returns `400 INVALID_STATUS`.

## 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, nullable: The reason sent with the refund request. `Pedido de reembolso do comprador` on a refund the payer requested and you approved, or that was approved automatically. `Reembolso feito pela YuvexPay` on a refund YuvexPay made after a payer's refund request: it debits the full amount returned to the payer, YuvexPay keeps the processing fee and the balance can go negative. `null` when none was sent and on refunds that reached YuvexPay from the payment network, such as the return of a PIX MED.
    - `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-10-02** `e1a5e956b369`: 1 breaking
  - the response property `refund/reason` became nullable for the status `200`
- **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

[Operation 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/d0e6ad21d782?raw)