{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars/sdk_sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["code-group"]},"type":"markdown"},"seo":{"title":"Refunding a transaction","description":"The specifications of Ratepay's APIs for easy payment transactions.","siteUrl":"https://docs.ratepay.com","keywords":"Ratepay developer portal, Ratepay api portal, Ratepay api reference docs","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"refunding-a-transaction","__idx":0},"children":["Refunding a transaction"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Refunds return funds from previously captured payments, whereas cancellations apply to authorized amounts that have not yet been captured."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use refunds for scenarios such as customer returns or billing corrections after capture."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, see the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.ratepay.com/docs/developer/api_integration/payment_2.0/payment_api_2.0"},"children":["Payment API 2.0 documentation"]},"."]},{"$$mdtype":"Tag","name":"CodeGroup","attributes":{"mode":"tabs"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","data-title":"Java","header":{"title":"Java","controls":{"copy":{}}},"source":"import com.ratepay.sdk.RefundOutcome;\nimport com.ratepay.sdk.model.api.payment.RefundRequest;\nimport java.math.BigDecimal;\n\nRefundRequest request = new RefundRequest(\n    new BigDecimal(\"249.00\"), // grossAmount, refunding the full captured amount\n    null, // items\n    null, // partnerOperationId\n    null, // partnerShopId\n    null, // specialItems\n    null  // vats\n);\n\nRefundOutcome outcome = client.refund(ratepayTransactionId, request, null);\n\nif (outcome.kind() == RefundOutcome.Kind.ACCEPTED) {\n    var accepted = (RefundOutcome.Accepted) outcome;\n    System.out.println(\"Refunded: \" + accepted.getRatepayRefundId());\n} else {\n    var declined = (RefundOutcome.Declined) outcome;\n    System.out.println(\"Refund declined: \" + declined.getDecline().getCategory());\n}\n","lang":"java"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","data-title":"Kotlin","header":{"title":"Kotlin","controls":{"copy":{}}},"source":"import com.ratepay.sdk.RefundOutcome\nimport com.ratepay.sdk.model.api.payment.RefundRequest\nimport java.math.BigDecimal\n\nval request = RefundRequest(grossAmount = BigDecimal(\"249.00\"))\n\nwhen (val outcome = client.refund(ratepayTransactionId, request)) {\n    is RefundOutcome.Accepted -> println(\"Refunded: ${outcome.ratepayRefundId}\")\n    is RefundOutcome.Declined -> println(\"Refund declined: ${outcome.decline.category}\")\n}\n","lang":"kotlin"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A common decline reason is requesting more than remains capturable/refundable, check"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Declined.decline.reasons"]}," for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REFUND_AMOUNT_TOO_HIGH"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"exceptions","__idx":1},"children":["Exceptions"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Exception"},"children":["Exception"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"HTTP Status Code"},"children":["HTTP Status Code"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayAuthException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["401/403"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayValidationException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400/422 with a structured decline payload"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayTransactionNotFoundException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["404"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayLegalException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["451"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayNetworkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["5xx/transport"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK does not perform client-side request validation before submission. Requests are validated by the API, which returns an error if validation fails."]}]},"headings":[{"value":"Refunding a transaction","id":"refunding-a-transaction","depth":1},{"value":"Exceptions","id":"exceptions","depth":2}],"frontmatter":{"seo":{"title":"Refunding a transaction"}},"lastModified":"2026-11-03T16:34:34.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/developer/sdk/guides/refunding-a-transaction","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}