Skip to content
/
Authorizing a Payment

Authorizing a Payment

This guide covers additional authorization scenarios beyond the basic example in Getting Started, including B2B buyers, SEPA Direct Debit, delivery information, device data, sales-channel settings, and CCD2 compliance.

Authorize a B2B payment with SEPA Direct Debit

The following example demonstrates how to authorize a B2B payment using SEPA Direct Debit (PAY_NOW / SEPA_DIRECT_DEBIT).

In addition to the standard authorization fields, the request includes:

  • Company information: The buyer's company details instead of personal buyer information.
  • Bank account details: The account holder's name and IBAN required for SEPA Direct Debit.
  • Delivery information: A delivery address different from the billing address.
  • Device information: The buyer's device information, typically required for online orders. See Device fingerprinting for details.
  • Sales channel: WEBSHOP to identify the transaction as an online purchase.
import com.ratepay.sdk.AuthorizeOutcome;
import com.ratepay.sdk.model.api.payment.*;
import java.math.BigDecimal;
import java.util.List;
import java.util.UUID;

PaymentMethod paymentMethod = new PaymentMethod(PaymentOption.PAY_NOW, TransferType.SEPA_DIRECT_DEBIT);

SepaDirectDebitPaymentDetails paymentDetails = new SepaDirectDebitPaymentDetails(
    new DebitBankAccount("DE89370400440532013000", "Acme Trading GmbH", null) // iban, owner, bic
);

Buyer buyer = new Buyer(
    new Address("Berlin", "DE", "Torstraße", "10119", null, "1"), // city, countryCode, street, zipCode, streetAddition, streetNumber
    new Contact("finance@acme-trading.example", "+49 30 9876543"),
    new Company("Acme Trading GmbH", "Max", "Mustermann", "DE123456789"), // company is mutually exclusive with person, as this is a B2B buyer
    null, // language
    null, // person
    null  // shopBuyerId
);

Delivery delivery = new Delivery(
    new Address("Berlin", "DE", "Lagerstraße", "12099", null, "5"), // address, the one delivery type set
    "Acme Trading GmbH",                // company, recipient at the delivery address
    null, null, null,                   // firstName, fullName, inStoreCollect
    null, null, null                    // lastName, pickUpBox, pickUpShop
);

Device device = new Device(
    null, null, null, null, null, null, // browser, fingerPrint, geoLocation, httpForwardedIpAddress, risk, screen
    "203.0.113.42",                     // sourceIpAddress, mandatory for online orders
    null                                // token
);

Options options = new Options(SalesChannel.WEBSHOP);

ShopBasket basket = new ShopBasket(
    new BigDecimal("249.00"), // grossAmount
    List.of(
        new Item(
            new BigDecimal("249.00"), "Ergonomic Office Chair", BigDecimal.ONE, new BigDecimal("19"), // grossUnitPrice, name, quantity, taxRate
            "SKU-2050", null, null, null, null, null, null, null, null
        )
    ),
    "INTEGRATION_TE_DACH", // partnerShopId
    null, null, UUID.randomUUID().toString(), null // vats, shopMerchantId, shopTransactionId, specialItems
);

AuthorizationRequest request = new AuthorizationRequest(
    buyer,
    "EUR",
    paymentMethod,
    List.of(basket),
    null,      // authorizationExpires
    null,      // complianceDetails
    delivery,
    device,
    options,
    null,      // partnerOperationId
    UUID.randomUUID().toString(),      // partnerTransactionId
    paymentDetails,
    null       // shops
);

AuthorizeOutcome outcome = client.authorize(request, null);

The authorize() method returns a typed AuthorizeOutcome. See Authorizing and capturing a payment for instructions on handling accepted, declined, and OTP-required outcomes.

Authorize with a CCD2 attestation token

For authorizations that require a Consumer Credit Directive II (CCD2) attestation token, use the authorize(request, attestationToken, idempotencyKey) method. The attestation token is obtained through generateSecci().

Important: The SDK sets the supplied token in request.complianceDetails.attestationToken, replacing any existing complianceDetails on the request.

Java and Kotlin conventions

When constructing authorization requests:

  • 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 null for optional fields that are not used.
  • Kotlin: Use named arguments to improve readability. When mocking overloaded authorize() methods, explicitly name the idempotency key argument (for example, authorize(any(), idempotencyKey = isNull())) to avoid overload ambiguity.

Error handling

The SDK distinguishes between business declines and API or network errors.

  • Business declines: Returned as AuthorizeOutcome.Declined, allowing you to handle declined payments without catching exceptions.
  • Validation and API errors: Thrown as exceptions, including RatepaySdkValidationException, RatepayAuthException, RatepayValidationException, RatepayNotFoundException, RatepayLegalException, and RatepayNetworkException.

For details on exception types, HTTP status codes, and error handling, see Exception hierarchy.

Next steps

Previous page
Next page