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;
@@ -17,7 +18,6 @@
 import com.checkout.payments.RiskRequest;
 import com.checkout.payments.ShippingDetails;
 import com.checkout.payments.ThreeDSRequest;
-import com.checkout.payments.request.PaymentRetryRequest;
 import com.checkout.payments.sender.Sender;
 import com.checkout.payments.PaymentMethodConfiguration;
 import com.google.gson.annotations.SerializedName;
@@ -177,10 +177,10 @@ public final class HostedPaymentRequest {
     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.

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;
@@ -18,7 +19,6 @@
 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.sender.PaymentSender;
 import com.google.gson.annotations.SerializedName;
 import lombok.Builder;
@@ -171,10 +171,10 @@ public final class PaymentLinkRequest {
     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.

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;

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

@@ -5,12 +5,21 @@
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
+/**
+ * Configuration of asynchronous retries.
+ */
 @Data
 @Builder
 @AllArgsConstructor
 @NoArgsConstructor
 public final class PaymentRetryRequest {
 
+    /**
+     * Indicates whether asynchronous retries are enabled for the payment.
+     * [Required]
+     */
+    private Boolean enabled;
+
     /**
      * Configuration of asynchronous Dunning retries.
      * [Optional]
@@ -23,24 +32,24 @@ public final class PaymentRetryRequest {
      */
     private DowntimeRetryRequest downtime;
 
-    // ========================================
-    // Deprecated — use dunning.enabled instead
-    // ========================================
-
-    /**
-     * @deprecated Use {@link DunningRetryRequest#enabled} via {@link #dunning} instead.
-     */
-    @Deprecated
-    private Boolean enabled;
-
     /**
-     * @deprecated Use {@link DunningRetryRequest#maxAttempts} via {@link #dunning} instead.
+     * Not part of the retry object in the API. If set, it is still sent at the top level of retry,
+     * where the API does not read it.
+     * [Optional]
+     *
+     * @deprecated Use {@link DunningRetryRequest#getMaxAttempts()} via {@link #dunning} instead.
+     * This property will be removed in the next major version.
      */
     @Deprecated
     private Integer maxAttempts;
 
     /**
-     * @deprecated Use {@link DunningRetryRequest#endAfterDays} via {@link #dunning} instead.
+     * Not part of the retry object in the API. If set, it is still sent at the top level of retry,
+     * where the API does not read it.
+     * [Optional]
+     *
+     * @deprecated Use {@link DunningRetryRequest#getEndAfterDays()} via {@link #dunning} instead.
+     * This property will be removed in the next major version.
      */
     @Deprecated
     private Integer endAfterDays;

src/main/java/com/checkout/payments/response/GetPaymentResponse.java

@@ -116,6 +116,10 @@ public final class GetPaymentResponse extends Resource {
 
     private List<PaymentActionSummary> actions;
 
+    /**
+     * Configuration relating to asynchronous retries.
+     * [Optional]
+     */
     private PaymentRetryResponse retry;
 
     private PanProcessedType panTypeProcessed;

src/main/java/com/checkout/payments/response/PaymentResponse.java

@@ -74,6 +74,10 @@ public final class PaymentResponse extends Resource implements Serializable {
 
     private String schemeId;
 
+    /**
+     * Configuration relating to asynchronous retries.
+     * [Optional]
+     */
     private PaymentRetryResponse retry;
 
     private String paymentIp;

src/main/java/com/checkout/payments/response/PaymentRetryResponse.java

@@ -1,24 +1,50 @@
 package com.checkout.payments.response;
 
+import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Data;
+import lombok.NoArgsConstructor;
 
 import java.time.Instant;
 
+/**
+ * Configuration relating to asynchronous retries. Returned by request a payment and by get payment details.
+ */
 @Data
 @Builder
+@NoArgsConstructor
+@AllArgsConstructor
 public final class PaymentRetryResponse {
 
     /**
      * Indicates whether asynchronous retries are enabled for the payment.
-     * [Optional]
+     * [Required]
      */
     private Boolean enabled;
 
+    /**
+     * The number of retries attempted so far. Minimum 0. Returned by get payment details only.
+     * [Optional]
+     */
+    private Integer attemptsMade;
+
+    /**
+     * The maximum number of authorization retry attempts, excluding the initial authorization.
+     * Minimum 1, maximum 15. Default: 6.
+     * [Optional]
+     */
     private Integer maxAttempts;
 
+    /**
+     * A timestamp that details the date on which the retry schedule expires, in ISO 8601 format.
+     * [Optional]
+     */
     private Instant endsOn;
 
+    /**
+     * A timestamp that details the date on which the next authorization attempt will take place, in ISO 8601 format.
+     * [Optional]
+     */
     private Instant nextAttemptOn;
 
 }

src/test/java/com/checkout/TestHelper.java

@@ -13,6 +13,7 @@
 import com.checkout.common.PaymentSourceType;
 import com.checkout.common.Phone;
 import com.checkout.common.Product;
+import com.checkout.handlepaymentsandpayouts.flow.entities.CustomerRetry;
 import com.checkout.instruments.previous.InstrumentCustomerRequest;
 import com.checkout.payments.Applepay;
 import com.checkout.payments.BillingDescriptor;
@@ -36,7 +37,6 @@
 import com.checkout.payments.hosted.HostedPaymentRequest;
 import com.checkout.payments.PaymentPurposeType;
 import com.checkout.payments.links.PaymentLinkRequest;
-import com.checkout.payments.request.PaymentRetryRequest;
 import com.checkout.payments.request.source.contexts.PaymentContextsKlarnaSource;
 import com.checkout.payments.request.source.contexts.PaymentContextsPayPalSource;
 import com.checkout.payments.request.source.contexts.PaymentContextsStcpaySource;
@@ -169,7 +169,7 @@ public static PaymentLinkRequest createPaymentLinksRequest(final String referenc
                 .metadata(Collections.singletonMap("key", "value"))
                 .threeDS(createThreeDS())
                 .risk(RiskRequest.builder().enabled(false).build())
-                .customerRetry(PaymentRetryRequest.builder()
+                .customerRetry(CustomerRetry.builder()
                         .maxAttempts(3)
                         .build())
                 .sender(PaymentInstrumentSender.builder()
@@ -265,7 +265,7 @@ public static HostedPaymentRequest createHostedPaymentRequest(final String refer
                 .risk(RiskRequest.builder()
                         .enabled(false)
                         .build())
-                .customerRetry(PaymentRetryRequest.builder()
+                .customerRetry(CustomerRetry.builder()
                         .maxAttempts(2)
                         .build())
                 .sender(PaymentInstrumentSender.builder()