{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars/sdk_sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["code-group","admonition"]},"type":"markdown"},"seo":{"title":"Authorizing and capturing a payment","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":"authorizing-and-capturing-a-payment","__idx":0},"children":["Authorizing and capturing a payment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this guide, you'll authorize and capture a test payment using the Ratepay Java SDK. You'll initialize the client, authorize a payment, handle the authorization outcome, and capture the payment."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Environment.INTEGRATION"]}," with Ratepay's shared test credentials. To request dedicated integration environment credentials, contact ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"mailto:integration@ratepay.com"},"children":["integration@ratepay.com"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"1-build-the-client","__idx":1},"children":["1. Build the client"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayClient"]}," using your API credentials and the integration environment."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For additional configuration options, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/developer/sdk/client/client-configuration"},"children":["Client configuration"]},"."]},{"$$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":"RatepayClient client = RatepayClient.builder()\n    .clientId(System.getenv(\"RATEPAY_CLIENT_ID\"))\n    .clientSecret(System.getenv(\"RATEPAY_CLIENT_SECRET\"))\n    .environment(Environment.INTEGRATION)\n    .build();\n","lang":"java"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","data-title":"Kotlin","header":{"title":"Kotlin","controls":{"copy":{}}},"source":"val client = RatepayClient {\n    clientId(System.getenv(\"RATEPAY_CLIENT_ID\"))\n    clientSecret(System.getenv(\"RATEPAY_CLIENT_SECRET\"))\n    environment(Environment.INTEGRATION)\n}\n","lang":"kotlin"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"2-authorize-a-payment","__idx":2},"children":["2. Authorize a payment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create an authorization request with the buyer's information, payment method, currency, and shopping basket."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This example uses Open Invoice (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OPEN_INVOICE"]},") with bank transfer (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BANK_TRANSFER"]},"), which does not require the buyer's bank details during authorization."]},{"$$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.AuthorizeOutcome;\nimport com.ratepay.sdk.model.api.payment.*;\nimport java.math.BigDecimal;\nimport java.time.LocalDate;\nimport java.util.List;\nimport java.util.UUID;\n\nvar partnerTransactionId = UUID.randomUUID().toString();\nAuthorizationRequest request = new AuthorizationRequest(\n    new Buyer(\n        new Address(\"Berlin\", \"DE\", \"Torstraße\", \"10119\", null, \"1\"), // city, countryCode, street, zipCode, streetAddition, streetNumber\n        new Contact(\"jane.doe@example.com\", \"+49 30 1234567\"),\n        null,   // company is mutually exclusive with person as this is a B2C buyer\n        null,   // language\n        new Person(LocalDate.of(1990, 4, 12), \"Jane\", \"Doe\", null), // dateOfBirth, firstName, lastName, title\n        null    // shopBuyerId\n    ),\n    \"EUR\",\n    new PaymentMethod(PaymentOption.OPEN_INVOICE, TransferType.BANK_TRANSFER),\n    List.of(\n        new ShopBasket(\n            new BigDecimal(\"29.99\"), // grossAmount\n            List.of(\n                new Item(\n                    new BigDecimal(\"29.99\"), \"Wireless Mouse\", BigDecimal.ONE, new BigDecimal(\"19\"), // grossUnitPrice, name, quantity, taxRate\n                    \"SKU-1001\", null, null, null, null, null, null, null, null\n                )\n            ),\n            \"SHOP-001\", // partnerShopId\n            null, null, partnerTransactionId, null // vats, shopMerchantId, shopTransactionId, specialItems\n        )\n    ),\n    null, null, null, null, null, null, partnerTransactionId, null, null\n);\n\nAuthorizeOutcome outcome = client.authorize(request, null); // null = let the SDK generate an idempotency key\nString ratepayTransactionId = outcome.ratepayTransactionId(); // always present, whatever the outcome\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.model.api.payment.*\nimport java.math.BigDecimal\nimport java.time.LocalDate\nimport java.util.UUID\n\nval partnerTransactionId = UUID.randomUUID().toString()\n\nval request = AuthorizationRequest(\n    paymentMethod = PaymentMethod(PaymentOption.OPEN_INVOICE, TransferType.BANK_TRANSFER),\n    currency = \"EUR\",\n    buyer = Buyer(\n        billingAddress = Address(street = \"Torstraße\", streetNumber = \"1\", zipCode = \"10119\", city = \"Berlin\", countryCode = \"DE\"),\n        contact = Contact(email = \"jane.doe@example.com\", phone = \"+49 30 1234567\"),\n        person = Person(firstName = \"Jane\", lastName = \"Doe\", dateOfBirth = LocalDate.of(1990, 4, 12)),\n    ),\n    shopBaskets = listOf(\n        ShopBasket(\n            partnerShopId = \"SHOP-001\",\n            grossAmount = BigDecimal(\"29.99\"),\n            items = listOf(\n                Item(\n                    grossUnitPrice = BigDecimal(\"29.99\"),\n                    name = \"Wireless Mouse\",\n                    taxRate = BigDecimal(\"19\"),\n                    quantity = BigDecimal.ONE,\n                    articleNumber = \"SKU-1001\",\n                ),\n            ),\n            vats = null,\n\t\t\tshopTransactionId = partnerTransactionId,\n        ),\n    ),\n    partnerTransactionId = partnerTransactionId,\n)\n\nval outcome = client.authorize(request) // idempotencyKey defaults to null → SDK generates one\nval ratepayTransactionId = outcome.ratepayTransactionId() // always present, whatever the outcome\n","lang":"kotlin"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For additional request fields, supported payment methods, and B2B buyer details, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/developer/sdk/guides/authorizing-a-transaction"},"children":["Authorizing a transaction"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"3-handle-the-outcome","__idx":3},"children":["3. Handle the outcome"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The authorization returns one of three typed outcomes, identified by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AuthorizeOutcome.Kind"]},"."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Payment declines are handled as business outcomes rather than 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":"Outcome Kind"},"children":["Outcome Kind"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCEPTED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The payment is authorized. You can proceed with capture once the order is fulfilled."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The authorization was declined. Inspect the decline category and reason to determine how to handle the result. Do not automatically retry the same request."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OTP_REQUIRED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The buyer must complete one-time passcode (OTP) verification before the authorization can be confirmed. See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/developer/sdk/guides/completing-otp-verification"},"children":["Completing OTP verification"]},"."]}]}]}]}]},{"$$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":"switch (outcome.kind()) {\n    case ACCEPTED -> {\n        var accepted = (AuthorizeOutcome.Accepted) outcome;\n        System.out.println(\"Authorized, expires \" + accepted.getAuthorizationExpires());\n    }\n    case DECLINED -> {\n        var declined = (AuthorizeOutcome.Declined) outcome;\n        System.out.println(\"Declined: \" + declined.getDecline().getCategory());\n    }\n    case OTP_REQUIRED -> {\n        var otp = (AuthorizeOutcome.OtpRequired) outcome;\n        System.out.println(\"OTP required: \" + otp.getOtpDetails().getMessage().getEn());\n    }\n}\n","lang":"java"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","data-title":"Kotlin","header":{"title":"Kotlin","controls":{"copy":{}}},"source":"when (outcome) {\n    is AuthorizeOutcome.Accepted -> println(\"Authorized, expires ${outcome.authorizationExpires}\")\n    is AuthorizeOutcome.Declined -> println(\"Declined: ${outcome.decline.category}\")\n    is AuthorizeOutcome.OtpRequired -> println(\"OTP required: ${outcome.otpDetails.message.en}\")\n}\n","lang":"kotlin"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"4-capture-the-transaction","__idx":4},"children":["4. Capture the transaction"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once the authorization is accepted, capture the payment when the order is fulfilled, typically upon shipment or order confirmation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the Ratepay transaction ID returned during authorization to submit the capture request."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This example captures the full authorized amount of €29.99. A successful capture returns a Ratepay capture ID."]},{"$$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.CaptureOutcome;\nimport com.ratepay.sdk.model.api.payment.CaptureRequest;\n\nCaptureRequest captureRequest = new CaptureRequest(\n    new BigDecimal(\"29.99\"), null, null, null, null, null, null, null, null\n);\n\nCaptureOutcome captureOutcome = client.capture(ratepayTransactionId, captureRequest, null);\n\nif (captureOutcome.kind() == CaptureOutcome.Kind.ACCEPTED) {\n    var accepted = (CaptureOutcome.Accepted) captureOutcome;\n    System.out.println(\"Captured \" + accepted.getRatepayCaptureId());\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.CaptureOutcome\nimport com.ratepay.sdk.model.api.payment.CaptureRequest\n\nval captureRequest = CaptureRequest(grossAmount = BigDecimal(\"29.99\"))\nval captureOutcome = client.capture(ratepayTransactionId, captureRequest)\n\nif (captureOutcome is CaptureOutcome.Accepted) {\n    println(\"Captured ${captureOutcome.ratepayCaptureId}\")\n}\n","lang":"kotlin"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For additional capture scenarios, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/developer/sdk/guides/capturing-a-transaction"},"children":["Capturing a transaction"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next","__idx":5},"children":["Next"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Explore additional ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/developer/sdk/guides/authorizing-a-transaction"},"children":["authorization fields"]},", ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/developer/sdk/guides/cancelling-a-transaction"},"children":["cancellations"]},", ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/developer/sdk/guides/refunding-a-transaction"},"children":["refunds"]},", ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/developer/sdk/guides/incremental-authorization"},"children":["incremental authorizations"]},"  and ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/developer/sdk/guides/adding-shipping-information"},"children":["adding shipping information"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Learn how to handle ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/developer/sdk/errors-and-resilience/exception-hierarchy"},"children":["exceptions"]},"."]}]}]},"headings":[{"value":"Authorizing and capturing a payment","id":"authorizing-and-capturing-a-payment","depth":1},{"value":"1. Build the client","id":"1-build-the-client","depth":2},{"value":"2. Authorize a payment","id":"2-authorize-a-payment","depth":2},{"value":"3. Handle the outcome","id":"3-handle-the-outcome","depth":2},{"value":"4. Capture the transaction","id":"4-capture-the-transaction","depth":2},{"value":"Next","id":"next","depth":2}],"frontmatter":{"seo":{"title":"Authorizing and capturing a payment"}},"lastModified":"2026-11-04T10:26:34.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/developer/sdk/getting-started/quickstart","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}