Skip to content
/
Authorizing and capturing...

Authorizing and capturing a payment

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.

Use Environment.INTEGRATION with Ratepay's shared test credentials. To request dedicated integration environment credentials, contact integration@ratepay.com.

1. Build the client

Create a RatepayClient using your API credentials and the integration environment.

For additional configuration options, see Client configuration.

RatepayClient client = RatepayClient.builder()
    .clientId(System.getenv("RATEPAY_CLIENT_ID"))
    .clientSecret(System.getenv("RATEPAY_CLIENT_SECRET"))
    .environment(Environment.INTEGRATION)
    .build();

2. Authorize a payment

Create an authorization request with the buyer's information, payment method, currency, and shopping basket.

This example uses Open Invoice (OPEN_INVOICE) with bank transfer (BANK_TRANSFER), which does not require the buyer's bank details during authorization.

import com.ratepay.sdk.AuthorizeOutcome;
import com.ratepay.sdk.model.api.payment.*;
import java.math.BigDecimal;
import java.time.LocalDate;
import java.util.List;
import java.util.UUID;

var partnerTransactionId = UUID.randomUUID().toString();
AuthorizationRequest request = new AuthorizationRequest(
    new Buyer(
        new Address("Berlin", "DE", "Torstraße", "10119", null, "1"), // city, countryCode, street, zipCode, streetAddition, streetNumber
        new Contact("jane.doe@example.com", "+49 30 1234567"),
        null,   // company is mutually exclusive with person as this is a B2C buyer
        null,   // language
        new Person(LocalDate.of(1990, 4, 12), "Jane", "Doe", null), // dateOfBirth, firstName, lastName, title
        null    // shopBuyerId
    ),
    "EUR",
    new PaymentMethod(PaymentOption.OPEN_INVOICE, TransferType.BANK_TRANSFER),
    List.of(
        new ShopBasket(
            new BigDecimal("29.99"), // grossAmount
            List.of(
                new Item(
                    new BigDecimal("29.99"), "Wireless Mouse", BigDecimal.ONE, new BigDecimal("19"), // grossUnitPrice, name, quantity, taxRate
                    "SKU-1001", null, null, null, null, null, null, null, null
                )
            ),
            "SHOP-001", // partnerShopId
            null, null, partnerTransactionId, null // vats, shopMerchantId, shopTransactionId, specialItems
        )
    ),
    null, null, null, null, null, null, partnerTransactionId, null, null
);

AuthorizeOutcome outcome = client.authorize(request, null); // null = let the SDK generate an idempotency key
String ratepayTransactionId = outcome.ratepayTransactionId(); // always present, whatever the outcome

For additional request fields, supported payment methods, and B2B buyer details, see Authorizing a transaction.

3. Handle the outcome

The authorization returns one of three typed outcomes, identified by AuthorizeOutcome.Kind.

Payment declines are handled as business outcomes rather than exceptions.

Outcome KindDescription
ACCEPTEDThe payment is authorized. You can proceed with capture once the order is fulfilled.
DECLINEDThe authorization was declined. Inspect the decline category and reason to determine how to handle the result. Do not automatically retry the same request.
OTP_REQUIREDThe buyer must complete one-time passcode (OTP) verification before the authorization can be confirmed. See Completing OTP verification.
switch (outcome.kind()) {
    case ACCEPTED -> {
        var accepted = (AuthorizeOutcome.Accepted) outcome;
        System.out.println("Authorized, expires " + accepted.getAuthorizationExpires());
    }
    case DECLINED -> {
        var declined = (AuthorizeOutcome.Declined) outcome;
        System.out.println("Declined: " + declined.getDecline().getCategory());
    }
    case OTP_REQUIRED -> {
        var otp = (AuthorizeOutcome.OtpRequired) outcome;
        System.out.println("OTP required: " + otp.getOtpDetails().getMessage().getEn());
    }
}

4. Capture the transaction

Once the authorization is accepted, capture the payment when the order is fulfilled, typically upon shipment or order confirmation.

Use the Ratepay transaction ID returned during authorization to submit the capture request.

This example captures the full authorized amount of €29.99. A successful capture returns a Ratepay capture ID.

import com.ratepay.sdk.CaptureOutcome;
import com.ratepay.sdk.model.api.payment.CaptureRequest;

CaptureRequest captureRequest = new CaptureRequest(
    new BigDecimal("29.99"), null, null, null, null, null, null, null, null
);

CaptureOutcome captureOutcome = client.capture(ratepayTransactionId, captureRequest, null);

if (captureOutcome.kind() == CaptureOutcome.Kind.ACCEPTED) {
    var accepted = (CaptureOutcome.Accepted) captureOutcome;
    System.out.println("Captured " + accepted.getRatepayCaptureId());
}

For additional capture scenarios, see Capturing a transaction.

Next

Previous page
Next page