fix(payments): align retry and customer retry types with the spec

src/main/java/com/checkout/handlepaymentsandpayouts/flow/entities/CustomerRetry.java

@@ -6,7 +6,9 @@
 import lombok.NoArgsConstructor;
 
 /**
- * Configuration for asynchronous retries
+ * Configures the parameters for customer retries. A customer retry is a payment attempt performed by the
+ * customer on the checkout page. This differs from authorization request retries performed in the back end
+ * by Checkout.com. Used by hosted payments, payment links and payment sessions.
  */
 @Data
 @Builder
@@ -15,8 +17,9 @@
 public final class CustomerRetry {
 
     /**
-     * The maximum number of authorization retry attempts, excluding the initial authorization. Default: 5
-     * [Optional]
+     * The maximum number of customer retry attempts, excluding the initial payment attempt.
+     * Minimum 0, maximum 5. Default: 5. The SDK sends 5 when not set.
+     * [Optional] for hosted payments and payment links; [Required] for payment sessions.
      */
     @Builder.Default
     private Integer maxAttempts = 5;

src/main/java/com/checkout/handlepaymentsandpayouts/flow/requests/PaymentSessionCreateRequest.java

@@ -48,7 +48,7 @@ public final class PaymentSessionCreateRequest extends PaymentSessionCreateBase
     private PaymentMethodConfiguration paymentMethodConfiguration;
 
     /**
-     * Configuration for asynchronous retries.
+     * Configuration for customer retries. When sent, max_attempts is required.
      * [Optional]
      */
     private CustomerRetry customerRetry;

src/main/java/com/checkout/handlepaymentsandpayouts/payments/postpayments/responses/requestapaymentorpayoutresponsecreated/retry/Retry.java

@@ -1,16 +1,14 @@
 package com.checkout.handlepaymentsandpayouts.payments.postpayments.responses.requestapaymentorpayoutresponsecreated.retry;
 
-import lombok.Builder;
-
 import lombok.AllArgsConstructor;
+import lombok.Builder;
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
 import java.time.Instant;
 
 /**
- * retry
- * Configuration relating to asynchronous retries
+ * Configuration relating to asynchronous retries.
  */
 @Data
 @Builder
@@ -20,17 +18,16 @@ public final class Retry {
 
     /**
      * Indicates whether asynchronous retries are enabled for the payment.
-     * [Optional]
+     * [Required]
      */
     private Boolean enabled;
 
     /**
-     * Default: 6 The maximum number of authorization retry attempts, excluding the initial authorization.
+     * The maximum number of authorization retry attempts, excluding the initial authorization.
+     * Minimum 1, maximum 15. Default: 6.
      * [Optional]
-     * [ 1 .. 15 ]
      */
-    @Builder.Default
-    private Integer maxAttempts = 6;
+    private Integer maxAttempts;
 
     /**
      * A timestamp that details the date on which the retry schedule expires, in ISO 8601 format.

src/main/java/com/checkout/payments/hosted/HostedPaymentRequest.java

@@ -5,6 +5,7 @@
 import com.checkout.common.CustomerRequest;
 import com.checkout.common.PaymentSourceType;
 import com.checkout.common.Product;
+import com.checkout.handlepaymentsandpayouts.flow.entities.CustomerRetry;
 import com.checkout.payments.AuthorizationType;
 import com.checkout.payments.BillingDescriptor;
 import com.checkout.payments.BillingInformation;
@@ -177,10 +178,10 @@
     private RiskRequest risk;
 
     /**
-     * The customer retry configuration for failed payments.
+     * Configures the parameters for customer retries (payment attempts performed by the customer on the checkout page).
      * [Optional]
      */
-    private PaymentRetryRequest customerRetry;
+    private CustomerRetry customerRetry;
 
     /**
      * The sender of the payment. Required for financial regulations in some jurisdictions.
@@ -245,4 +246,80 @@
      * Default: "Final"
      */
     private AuthorizationType authorizationType;
+
+
+    /**
+     * Configures the parameters for customer retries. Written by hand because Lombok does not generate a
+     * setter when another method with the same name exists.
+     *
+     * @param customerRetry the customer retry configuration
+     */
+    public void setCustomerRetry(final CustomerRetry customerRetry) {
+        this.customerRetry = customerRetry;
+    }
+
+    /**
+     * Configures customer retries from a {@link PaymentRetryRequest}. Only its max attempts value is kept,
+     * because customer_retry only accepts max_attempts. A null request clears the customer retry; a request
+     * without max attempts sets the {@link CustomerRetry} default.
+     *
+     * @param customerRetry the retry configuration to convert
+     * @deprecated Use {@link #setCustomerRetry(CustomerRetry)} instead.
+     * This method will be removed in the next major version.
+     */
+    @Deprecated
+    public void setCustomerRetry(final PaymentRetryRequest customerRetry) {
+        this.customerRetry = toCustomerRetry(customerRetry);
+    }
+
+    /**
+     * Converts the deprecated {@link PaymentRetryRequest} overloads to {@link CustomerRetry}.
+     *
+     * @deprecated Only used by the deprecated {@link PaymentRetryRequest} overloads; removed with them in the next
+     * major version.
+     */
+    @Deprecated
+    private static CustomerRetry toCustomerRetry(final PaymentRetryRequest customerRetry) {
+        if (customerRetry == null) {
+            return null;
+        }
+        if (customerRetry.getMaxAttempts() == null) {
+            return CustomerRetry.builder().build();
+        }
+        return CustomerRetry.builder().maxAttempts(customerRetry.getMaxAttempts()).build();
+    }
+
+    /**
+     * Builder for {@link HostedPaymentRequest}. Only the customer retry methods are written by hand; every other
+     * method is generated by Lombok.
+     */
+    public static class HostedPaymentRequestBuilder {
+
+        /**
+         * Configures the parameters for customer retries.
+         *
+         * @param customerRetry the customer retry configuration
+         * @return this builder
+         */
+        public HostedPaymentRequestBuilder customerRetry(final CustomerRetry customerRetry) {
+            this.customerRetry = customerRetry;
+            return this;
+        }
+
+        /**
+         * Configures customer retries from a {@link PaymentRetryRequest}. Only its max attempts value is kept,
+         * because customer_retry only accepts max_attempts. A null request clears the customer retry; a request
+         * without max attempts sends the {@link CustomerRetry} default.
+         *
+         * @param customerRetry the retry configuration to convert
+         * @return this builder
+         * @deprecated Use {@link #customerRetry(CustomerRetry)} instead.
+         * This method will be removed in the next major version.
+         */
+        @Deprecated
+        public HostedPaymentRequestBuilder customerRetry(final PaymentRetryRequest customerRetry) {
+            this.customerRetry = toCustomerRetry(customerRetry);
+            return this;
+        }
+    }
 }

src/main/java/com/checkout/payments/links/PaymentLinkRequest.java

@@ -5,6 +5,7 @@
 import com.checkout.common.CustomerRequest;
 import com.checkout.common.PaymentSourceType;
 import com.checkout.common.Product;
+import com.checkout.handlepaymentsandpayouts.flow.entities.CustomerRetry;
 import com.checkout.payments.AuthorizationType;
 import com.checkout.payments.BillingDescriptor;
 import com.checkout.payments.BillingInformation;
@@ -17,8 +18,8 @@
 import com.checkout.payments.RiskRequest;
 import com.checkout.payments.ShippingDetails;
 import com.checkout.payments.ThreeDSRequest;
-import com.checkout.payments.PaymentInstruction;
 import com.checkout.payments.request.PaymentRetryRequest;
+import com.checkout.payments.PaymentInstruction;
 import com.checkout.payments.sender.PaymentSender;
 import com.google.gson.annotations.SerializedName;
 import lombok.Builder;
@@ -171,10 +172,10 @@
     private RiskRequest risk;
 
     /**
-     * The customer retry configuration for failed payments.
+     * Configures the parameters for customer retries (payment attempts performed by the customer on the checkout page).
      * [Optional]
      */
-    private PaymentRetryRequest customerRetry;
+    private CustomerRetry customerRetry;
 
     /**
      * The sender of the payment. Required for financial regulations in some jurisdictions.
@@ -232,4 +233,80 @@
      * Default: "Final"
      */
     private AuthorizationType authorizationType;
+
+
+    /**
+     * Configures the parameters for customer retries. Written by hand because Lombok does not generate a
+     * setter when another method with the same name exists.
+     *
+     * @param customerRetry the customer retry configuration
+     */
+    public void setCustomerRetry(final CustomerRetry customerRetry) {
+        this.customerRetry = customerRetry;
+    }
+
+    /**
+     * Configures customer retries from a {@link PaymentRetryRequest}. Only its max attempts value is kept,
+     * because customer_retry only accepts max_attempts. A null request clears the customer retry; a request
+     * without max attempts sets the {@link CustomerRetry} default.
+     *
+     * @param customerRetry the retry configuration to convert
+     * @deprecated Use {@link #setCustomerRetry(CustomerRetry)} instead.
+     * This method will be removed in the next major version.
+     */
+    @Deprecated
+    public void setCustomerRetry(final PaymentRetryRequest customerRetry) {
+        this.customerRetry = toCustomerRetry(customerRetry);
+    }
+
+    /**
+     * Converts the deprecated {@link PaymentRetryRequest} overloads to {@link CustomerRetry}.
+     *
+     * @deprecated Only used by the deprecated {@link PaymentRetryRequest} overloads; removed with them in the next
+     * major version.
+     */
+    @Deprecated
+    private static CustomerRetry toCustomerRetry(final PaymentRetryRequest customerRetry) {
+        if (customerRetry == null) {
+            return null;
+        }
+        if (customerRetry.getMaxAttempts() == null) {
+            return CustomerRetry.builder().build();
+        }
+        return CustomerRetry.builder().maxAttempts(customerRetry.getMaxAttempts()).build();
+    }
+
+    /**
+     * Builder for {@link PaymentLinkRequest}. Only the customer retry methods are written by hand; every other
+     * method is generated by Lombok.
+     */
+    public static class PaymentLinkRequestBuilder {
+
+        /**
+         * Configures the parameters for customer retries.
+         *
+         * @param customerRetry the customer retry configuration
+         * @return this builder
+         */
+        public PaymentLinkRequestBuilder customerRetry(final CustomerRetry customerRetry) {
+            this.customerRetry = customerRetry;
+            return this;
+        }
+
+        /**
+         * Configures customer retries from a {@link PaymentRetryRequest}. Only its max attempts value is kept,
+         * because customer_retry only accepts max_attempts. A null request clears the customer retry; a request
+         * without max attempts sends the {@link CustomerRetry} default.
+         *
+         * @param customerRetry the retry configuration to convert
+         * @return this builder
+         * @deprecated Use {@link #customerRetry(CustomerRetry)} instead.
+         * This method will be removed in the next major version.
+         */
+        @Deprecated
+        public PaymentLinkRequestBuilder customerRetry(final PaymentRetryRequest customerRetry) {
+            this.customerRetry = toCustomerRetry(customerRetry);
+            return this;
+        }
+    }
 }

src/main/java/com/checkout/payments/request/DowntimeRetryRequest.java

@@ -5,15 +5,18 @@
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
+/**
+ * Configuration of Downtime retries.
+ */
 @Data
 @Builder
 @AllArgsConstructor
 @NoArgsConstructor
 public final class DowntimeRetryRequest {
 
     /**
-     * Whether downtime retries are enabled.
-     * [Optional]
+     * Indicates if Checkout.com retries the payment when it's declined due to issuer or acquirer downtime.
+     * [Required]
      */
     private Boolean enabled;
 

src/main/java/com/checkout/payments/request/DunningRetryRequest.java

@@ -5,26 +5,31 @@
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
+/**
+ * Configuration of Dunning retries.
+ */
 @Data
 @Builder
 @AllArgsConstructor
 @NoArgsConstructor
 public final class DunningRetryRequest {
 
     /**
-     * Whether dunning retries are enabled.
-     * [Optional]
+     * Indicates if Checkout.com retries the payment when it's declined with a supported decline code.
+     * [Required]
      */
     private Boolean enabled;
 
     /**
-     * The maximum number of retry attempts.
+     * The maximum number of authorization retry attempts, excluding the initial authorization.
+     * Minimum 1, maximum 15. Default: 6.
      * [Optional]
      */
     private Integer maxAttempts;
 
     /**
-     * The number of days after which retries stop.
+     * The maximum number of days between the initial request and the final retry attempt.
+     * Minimum 1, maximum 60. Default: 30.
      * [Optional]
      */
     private Integer endAfterDays;

src/main/java/com/checkout/payments/request/PaymentRequest.java

@@ -253,7 +253,7 @@ public final class PaymentRequest {
     private List<ProductRequest> items;
 
     /**
-     * The retry configuration for failed payment attempts.
+     * Configuration of asynchronous retries.
      * [Optional]
      */
     private PaymentRetryRequest retry;