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

# Create Refund for a Payment

`POST /payments-refund/{id}/refund`

## Request

- The document declares no server URL.
- Auth: none declared. Required headers: `ApiKey`, `MerchantId`, `Environment`

This endpoint allows you to create a refund for a payment. The refund amount plus its fees must be covered by the available balance of your collection account: otherwise the request is refused with a 409 `refund_exceeds_available_balance`, whose message states the maximum refundable amount.

## Path parameters

- `id` string, required

## Headers

- `ApiKey` string, required
- `MerchantId` string, required
- `Environment` 'live' | 'sandbox', required

## Request body

- CreatePaymentRefundRequestDto
  - `amount` number, required: The amount to refund
  - `reasonCode` string, required: The reason for the refund
  - `reasonDetails` string, required: The details of the reason for the refund

## Response `202`

- CreatePaymentRefundResponseDto
  - `id` number, required: The payment refund record id

## Other responses

- `400`: Bad Request
- `401`: Wrong credentials
- `403`: Forbidden
- `404`: Not Found
- `409`: Invalid request
- `429`: ThrottlerException: Too Many Requests
- `500`: Internal error
- `503`: Service unavailable

## Changes

- **2026-11-03** `f6d3f87df5e0`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/hub2/apis/hub2-service-api/changes/payments-refund/:id/refund/post.md)

---

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