---
title: "Refund Payment"
method: POST
path: "/api/v2/payments/{payment_id}/refund"
tags: ["Payments"]
---

# Refund Payment

`POST /api/v2/payments/{payment_id}/refund`

Process a full refund for a payment.

Refunds always settle the remaining refundable balance for the selected payment.
If that payment is part of a shared Moyasar charge, set
``allow_refund_multiple_related_payments`` to true to refund every payment that was
tied to the same charge.

## Path parameters

- `payment_id` string, uuid, required — Unique identifier (UUID) of the payment to refund

## Request body

- PaymentRefundRequest
  - `refund_reason` 'REQUESTED_BY_CUSTOMER' | 'DUPLICATE' | 'FRAUDULENT' | 'OTHER', required
  - `refund_note` string, nullable — Optional note explaining the refund reason
  - `allow_refund_multiple_related_payments` boolean — If true and the customer paid multiple payments at the same time (single transaction), refund all related payments instead of only the requested payment. Use this when the payment was part of a multi-payment transaction.

## Response `200`

Successful Response

- PaymentResponse
  - `id` string, uuid — Unique identifier (UUID) of the payment
  - `amount` string — Payment amount
  - `currency` 'SAR' | 'USD' | 'EUR' | 'GBP' | 'AED' | 'BHD' | 'KWD' | 'OMR' | 'QAR' — ISO 4217 currency codes supported by Moyasar. Includes all currencies supported by Moyasar payment gateway.
  - `scheduled_on` string — Scheduled date and time for the payment
  - `type` 'INITIAL' | 'INSTALLMENT' | 'SPLIT_PREPAID' | 'SPLIT_REMAINDER'
  - `payment_method` 'MADA' | 'MASTERCARD' | 'VISA' | 'APPLE_PAY' | 'SAMSUNG_PAY' | 'AMEX' | 'CASH' | 'PGW_CARD_UNSPECIFIED' | 'BANK_TRANSFER' | 'CARD' | 'QURRAH' | 'BNPL'
  - `current_status` 'PENDING' | 'PROCESSING' | 'FAILED_INITIATION' | 'SUCCEEDED' | 'FAILED' | 'CANCELED' | 'UNDER_REVIEW' | 'EXPIRED' | 'SETTLED' | 'REFUNDED' | 'PARTIALLY_REFUNDED'
  - `payed_at` string, date-time, nullable — Date and time when the payment was completed
  - `refunded_at` string, date-time, nullable — Date and time of the most recent refund
  - `refund_reason` 'REQUESTED_BY_CUSTOMER' | 'DUPLICATE' | 'FRAUDULENT' | 'OTHER'
  - `refund_note` string, nullable — Note for the most recent refund if set
  - `amount_refunded` string — Sum of all refund rows for this payment
  - `refunds` PaymentRefundResponse[] — Refund history for this payment
    - `id` string, uuid — Unique identifier of the refund row
    - `amount_refunded` string — Amount refunded in this refund
    - `refunded_at` string, date-time — When this refund was recorded
    - `refund_reason` 'REQUESTED_BY_CUSTOMER' | 'DUPLICATE' | 'FRAUDULENT' | 'OTHER'
    - `refund_note` string, nullable — Note explaining the refund if applicable
  - `latest_pgw_message` string, nullable — Latest payment gateway message for this payment
  - `amount_in_smallest_unit` integer — Payment amount in smallest currency unit (e.g. halala for SAR).

## Other responses

- `400` — Multiple payments were paid in a single transaction. Set 'allow_refund_multiple_related_payments' to true to refund all related payments.
- `422` — Validation Error

---

[API](https://skmtc.dev/streampay/apis/stream-app.md) · [All operations](https://skmtc.dev/streampay/apis/stream-app/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/streampay/stream-app/revisions/515eeea7d260/schema)