{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars/sdk_sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["code-group"]},"type":"markdown"},"seo":{"title":"Authorizing 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-a-payment","__idx":0},"children":["Authorizing a Payment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide covers additional authorization scenarios beyond the basic example in ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/developer/sdk/getting-started/quickstart"},"children":["Getting Started"]},", including B2B buyers, SEPA Direct Debit, delivery information, device data, sales-channel settings, and CCD2 compliance."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authorize-a-b2b-payment-with-sepa-direct-debit","__idx":1},"children":["Authorize a B2B payment with SEPA Direct Debit"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example demonstrates how to authorize a B2B payment using SEPA Direct Debit (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAY_NOW"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SEPA_DIRECT_DEBIT"]},")."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In addition to the standard authorization fields, the request includes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Company information:"]}," The buyer's company details instead of personal buyer information."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bank account details:"]}," The account holder's name and IBAN required for SEPA Direct Debit."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Delivery information:"]}," A delivery address different from the billing address."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Device information:"]}," The buyer's device information, typically required for online orders. See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/developer/device_fingerprinting/device_fingerprinting"},"children":["Device fingerprinting"]}," for details."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sales channel:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WEBSHOP"]}," to identify the transaction as an online purchase."]}]},{"$$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.util.List;\nimport java.util.UUID;\n\nPaymentMethod paymentMethod = new PaymentMethod(PaymentOption.PAY_NOW, TransferType.SEPA_DIRECT_DEBIT);\n\nSepaDirectDebitPaymentDetails paymentDetails = new SepaDirectDebitPaymentDetails(\n    new DebitBankAccount(\"DE89370400440532013000\", \"Acme Trading GmbH\", null) // iban, owner, bic\n);\n\nBuyer buyer = new Buyer(\n    new Address(\"Berlin\", \"DE\", \"Torstraße\", \"10119\", null, \"1\"), // city, countryCode, street, zipCode, streetAddition, streetNumber\n    new Contact(\"finance@acme-trading.example\", \"+49 30 9876543\"),\n    new Company(\"Acme Trading GmbH\", \"Max\", \"Mustermann\", \"DE123456789\"), // company is mutually exclusive with person, as this is a B2B buyer\n    null, // language\n    null, // person\n    null  // shopBuyerId\n);\n\nDelivery delivery = new Delivery(\n    new Address(\"Berlin\", \"DE\", \"Lagerstraße\", \"12099\", null, \"5\"), // address, the one delivery type set\n    \"Acme Trading GmbH\",                // company, recipient at the delivery address\n    null, null, null,                   // firstName, fullName, inStoreCollect\n    null, null, null                    // lastName, pickUpBox, pickUpShop\n);\n\nDevice device = new Device(\n    null, null, null, null, null, null, // browser, fingerPrint, geoLocation, httpForwardedIpAddress, risk, screen\n    \"203.0.113.42\",                     // sourceIpAddress, mandatory for online orders\n    null                                // token\n);\n\nOptions options = new Options(SalesChannel.WEBSHOP);\n\nShopBasket basket = new ShopBasket(\n    new BigDecimal(\"249.00\"), // grossAmount\n    List.of(\n        new Item(\n            new BigDecimal(\"249.00\"), \"Ergonomic Office Chair\", BigDecimal.ONE, new BigDecimal(\"19\"), // grossUnitPrice, name, quantity, taxRate\n            \"SKU-2050\", null, null, null, null, null, null, null, null\n        )\n    ),\n    \"INTEGRATION_TE_DACH\", // partnerShopId\n    null, null, UUID.randomUUID().toString(), null // vats, shopMerchantId, shopTransactionId, specialItems\n);\n\nAuthorizationRequest request = new AuthorizationRequest(\n    buyer,\n    \"EUR\",\n    paymentMethod,\n    List.of(basket),\n    null,      // authorizationExpires\n    null,      // complianceDetails\n    delivery,\n    device,\n    options,\n    null,      // partnerOperationId\n    UUID.randomUUID().toString(),      // partnerTransactionId\n    paymentDetails,\n    null       // shops\n);\n\nAuthorizeOutcome outcome = client.authorize(request, null);\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.util.UUID\n\nval request = AuthorizationRequest(\n    paymentMethod = PaymentMethod(PaymentOption.PAY_NOW, TransferType.SEPA_DIRECT_DEBIT),\n    currency = \"EUR\",\n    buyer = Buyer(\n        billingAddress = Address(street = \"Torstraße\", streetNumber = \"1\", zipCode = \"10119\", city = \"Berlin\", countryCode = \"DE\"),\n        contact = Contact(email = \"finance@acme-trading.example\", phone = \"+49 30 9876543\"),\n        company = Company(name = \"Acme Trading GmbH\", firstName = \"Max\", lastName = \"Mustermann\", vatId = \"DE123456789\"),\n    ),\n    shopBaskets = listOf(\n        ShopBasket(\n            partnerShopId = \"INTEGRATION_TE_DACH\",\n            grossAmount = BigDecimal(\"249.00\"),\n            items = listOf(\n                Item(\n                    grossUnitPrice = BigDecimal(\"249.00\"),\n                    name = \"Ergonomic Office Chair\",\n                    taxRate = BigDecimal(\"19\"),\n                    quantity = BigDecimal.ONE,\n                    articleNumber = \"SKU-2050\",\n                ),\n            ),\n            vats = null,\n            shopTransactionId = UUID.randomUUID().toString(),\t\t\t\n        ),\n    ),\n    options = Options(salesChannel = SalesChannel.WEBSHOP),\n    delivery = Delivery(\n        company = \"Acme Trading GmbH\",\n        address = Address(street = \"Lagerstraße\", streetNumber = \"5\", zipCode = \"12099\", city = \"Berlin\", countryCode = \"DE\"),\n    ),\n    device = Device(sourceIpAddress = \"203.0.113.42\"),\n    partnerTransactionId = UUID.randomUUID().toString(),\n    paymentDetails = SepaDirectDebitPaymentDetails(\n        debitBankAccount = DebitBankAccount(owner = \"Acme Trading GmbH\", iban = \"DE89370400440532013000\"),\n    ),\n)\n\nval outcome = client.authorize(request)\n","lang":"kotlin"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authorize()"]}," method returns a typed ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AuthorizeOutcome"]},". See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/developer/sdk/getting-started/quickstart"},"children":["Authorizing and capturing a payment"]}," for instructions on handling accepted, declined, and OTP-required outcomes."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authorize-with-a-ccd2-attestation-token","__idx":2},"children":["Authorize with a CCD2 attestation token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For authorizations that require a Consumer Credit Directive II (CCD2) attestation token, use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authorize(request, attestationToken, idempotencyKey)"]}," method. The attestation token is obtained through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["generateSecci()"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Important:"]}," The SDK sets the supplied token in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["request.complianceDetails.attestationToken"]},", replacing any existing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["complianceDetails"]}," on the request."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"java-and-kotlin-conventions","__idx":3},"children":["Java and Kotlin conventions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When constructing authorization requests:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Java:"]}," Request models use positional constructors. Provide arguments in the declared order, as arguments of the same type may compile even when placed incorrectly. Pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," for optional fields that are not used."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Kotlin:"]}," Use named arguments to improve readability. When mocking overloaded ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authorize()"]}," methods, explicitly name the idempotency key argument (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authorize(any(), idempotencyKey = isNull())"]},") to avoid overload ambiguity."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling","__idx":4},"children":["Error handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK distinguishes between business declines and API or network errors."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Business declines:"]}," Returned as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AuthorizeOutcome.Declined"]},", allowing you to handle declined payments without catching exceptions."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Validation and API errors:"]}," Thrown as exceptions, including ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepaySdkValidationException"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayAuthException"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayValidationException"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayNotFoundException"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayLegalException"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayNetworkException"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For details on exception types, HTTP status codes, and error handling, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/developer/sdk/errors-and-resilience/exception-hierarchy"},"children":["Exception hierarchy"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":5},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/developer/sdk/guides/completing-otp-verification"},"children":["Completing OTP verification"]}," when authorization returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AuthorizeOutcome.OtpRequired"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/developer/sdk/guides/capturing-a-transaction"},"children":["Capturing"]}," an accepted authorization."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/developer/sdk/guides/incremental-authorization"},"children":["Increase the amount of an existing authorization"]},"."]}]}]},"headings":[{"value":"Authorizing a Payment","id":"authorizing-a-payment","depth":1},{"value":"Authorize a B2B payment with SEPA Direct Debit","id":"authorize-a-b2b-payment-with-sepa-direct-debit","depth":2},{"value":"Authorize with a CCD2 attestation token","id":"authorize-with-a-ccd2-attestation-token","depth":2},{"value":"Java and Kotlin conventions","id":"java-and-kotlin-conventions","depth":2},{"value":"Error handling","id":"error-handling","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"seo":{"title":"Authorizing a Payment"}},"lastModified":"2026-11-03T16:42:42.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/developer/sdk/guides/authorizing-a-transaction","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}