# Referenced Refund Payment

A referenced refund is a refund that is processed using the original payment’s transaction reference.  
It ensures that the refund is directly linked to the initial payment, providing accurate reconciliation and audit tracking.

If you don't have, or don't want to use, the original payment's reference, use an [Unreferenced Refund](./unreferenced-refund.md) instead, but be aware that it can fail more often, so use it only as a last resort.

```admonition
icon: fas fa-warning-triangle
title: Note
content: It is recommended that your ePOS application provides a controlled way to issue refunds, such as requiring a manager password or restricted user permissions, to prevent unauthorized refunds.
```

As mentioned in the [Make Payment](./make-payment.md) section, you need to store the `gatewayPaymentId` included in `PaymentStateDetails` to access it later and pass it to the refund function.

```tabs
    tab:
      title: Kotlin (callbacks)
      content:
        ```kotlin
        val refundResultSubscription = teyaPosLinkSDK.transactionsApi.refundPayment(
            paymentId = paymentId, // The gatewayPaymentId of the payment you want to refund
            amount = amount, // Amount in minor units
            currency = "GBP" // The ISO 4217 currency code (e.g., "GBP", "EUR"). Should match the original payment one
        )
        ```
    tab:
      title: Kotlin (coroutines)
      content:
        ```kotlin
        val refundResult = teyaPosLinkSDK.transactions.refundPayment(
            paymentId = paymentId, // The gatewayPaymentId of the payment you want to refund
            amount = amount, // Amount in minor units
            currency = "GBP" // The ISO 4217 currency code (e.g., "GBP", "EUR"). Should match the original payment one
        )
        ```
    tab:
      title: Java
      content:
        ```java
        RefundResultSubscription refundResultSubscription = teyaPosLinkSDK.getTransactionsApi().refundPayment(
                paymentId, // paymentId: The gatewayPaymentId of the payment you want to refund
                amount, // amount: Amount in minor units
                "GBP"   // currency: The ISO 4217 currency code (e.g., "GBP", "EUR").
        );
        ```
```

```admonition
icon: fas fa-warning-triangle
title: Note
content: |
    You need to specify the `amount` because **partial refunds** are supported. For example, if the original payment was **£2.99**, you don't have to refund the full amount, you can refund a portion of it, such as **£1.00**.
    Please note that the `amount` cannot exceed the total transaction amount.
```

## Refund request result

To receive the refund result, you need to subscribe to the `RefundResultSubscription` object returned by the `refundPayment` function. The listener will receive the final `ResultDetails`, which contains the outcome of the refund process.

The coroutines API has nothing to subscribe to: `refundPayment` suspends until the outcome is known and returns a `RefundResultDetails` directly.

```tabs
    tab:
      title: Kotlin (callbacks)
      content:
        ```kotlin
        refundResultSubscription.subscribe(object : RefundResultSubscription.RefundResultListener {
            override fun onRefundResult(refundResult: RefundResultSubscription.ResultDetails) {
                // Handle refund result here
            }
        })
        ```
    tab:
      title: Kotlin (coroutines)
      content:
        ```kotlin
        when (refundResult.result) {
            RefundResult.Success -> println("Refunded: ${refundResult.gatewayRefundId}")
            else -> println("Refund failed: ${refundResult.result} ${refundResult.debugErrorMessage}")
        }
        ```
    tab:
      title: Java
      content:
        ```java
        refundResultSubscription.subscribe(refundResult -> {
            // Handle refund result here
        });
        ```
```

## Refund Interface

The SDK does not currently provide a built-in UI to display refund progress.  
It is recommended that the ePOS application implement its own user interface to present refund status and responses to the user.  
A native refund progress UI is planned for a future SDK release.