# Refunding a transaction

Refunds return funds from previously captured payments, whereas cancellations apply to authorized amounts that have not yet been captured.

Use refunds for scenarios such as customer returns or billing corrections after capture.

For more information, see the [Payment API 2.0 documentation](https://docs.ratepay.com/docs/developer/api_integration/payment_2.0/payment_api_2.0).


```java Java
import com.ratepay.sdk.RefundOutcome;
import com.ratepay.sdk.model.api.payment.RefundRequest;
import java.math.BigDecimal;

RefundRequest request = new RefundRequest(
    new BigDecimal("249.00"), // grossAmount, refunding the full captured amount
    null, // items
    null, // partnerOperationId
    null, // partnerShopId
    null, // specialItems
    null  // vats
);

RefundOutcome outcome = client.refund(ratepayTransactionId, request, null);

if (outcome.kind() == RefundOutcome.Kind.ACCEPTED) {
    var accepted = (RefundOutcome.Accepted) outcome;
    System.out.println("Refunded: " + accepted.getRatepayRefundId());
} else {
    var declined = (RefundOutcome.Declined) outcome;
    System.out.println("Refund declined: " + declined.getDecline().getCategory());
}
```


```kotlin Kotlin
import com.ratepay.sdk.RefundOutcome
import com.ratepay.sdk.model.api.payment.RefundRequest
import java.math.BigDecimal

val request = RefundRequest(grossAmount = BigDecimal("249.00"))

when (val outcome = client.refund(ratepayTransactionId, request)) {
    is RefundOutcome.Accepted -> println("Refunded: ${outcome.ratepayRefundId}")
    is RefundOutcome.Declined -> println("Refund declined: ${outcome.decline.category}")
}
```

A common decline reason is requesting more than remains capturable/refundable, check
`Declined.decline.reasons` for `REFUND_AMOUNT_TOO_HIGH`.

## Exceptions

| Exception | HTTP Status Code |
|  --- | --- |
| `RatepayAuthException` | 401/403 |
| `RatepayValidationException` | 400/422 with a structured decline payload |
| `RatepayTransactionNotFoundException` | 404 |
| `RatepayLegalException` | 451 |
| `RatepayNetworkException` | 5xx/transport |


The SDK does not perform client-side request validation before submission. Requests are validated by the API, which returns an error if validation fails.