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.
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());
}A common decline reason is requesting more than remains capturable/refundable, check Declined.decline.reasons for REFUND_AMOUNT_TOO_HIGH.
| 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.