---
title: "Refund a successful payment, fully or partially"
method: POST
path: "/v1/payments/{refNo}/refund"
tags: ["external-payments"]
---

# Refund a successful payment, fully or partially

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

## Path parameters

- `refNo` string, required

## Request body

- RefundExternalPaymentDto
  - `amount` string — Amount to refund. Omit for the full remaining balance.
  - `reason` string — Free-text reason, stored in the ledger only.

## Response `200`

- ExternalPaymentResponseDto
  - `refNo` string, required
  - `clientReference` string
  - `gateway` string, required
  - `status` 'pending' | 'processing' | 'success' | 'failed' | 'cancelled' | 'refunded' | 'expired', required
  - `amount` string, required
  - `currency` string, required
  - `description` string, required
  - `paymentUrl` string — Send the customer here. Present while the payment can still be paid.
  - `returnUrl` string, required
  - `gatewayTransactionId` string
  - `bankReference` string
  - `responseCode` string — Raw gateway result code (RevPay Appendix C)
  - `errorDescription` string
  - `paymentMethod` string — RevPay Payment_ID actually used
  - `refundedAmount` string, required
  - `createdAt` string, date-time, required
  - `completedAt` string, date-time

## Other responses

- `400` — Payment not refundable, amount exceeds balance, or gateway rejected the refund

## Changes

- **2026-09-17** `f7cc9325b5b7` — 1 info
  - endpoint added

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

---

[API](https://skmtc.dev/tonewow/apis/tonewow-database-api.md) · [All operations](https://skmtc.dev/tonewow/apis/tonewow-database-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tonewow/apis/tonewow-database-api/revisions/60d5bbdc852a?raw)