fix(setups): align the payment setup request shape with the spec

src/main/java/com/checkout/handlepaymentsandpayouts/setups/entities/order/OrderSubMerchant.java

@@ -17,24 +17,27 @@
 public final class OrderSubMerchant {
 
     /**
-     * The unique identifier of the sub-merchant
+     * The unique identifier for the sub-merchant.
+     * [Optional]
      */
     private String id;
 
     /**
-     * The category of products or services offered by the sub-merchant
+     * The product category for the sub-merchant.
+     * [Optional]
      */
     private String productCategory;
 
     /**
-     * The number of trades or transactions the sub-merchant has conducted
+     * The number of orders the sub-merchant has processed.
+     * [Optional]
      */
-    private Integer numberOfTrades;
+    private Integer numberOfSales;
 
     /**
      * The date the sub-merchant was registered.
      * [Optional]
      * Format: yyyy-MM-dd
      */
     private LocalDate registrationDate;
-}
+}

src/main/java/com/checkout/handlepaymentsandpayouts/setups/entities/paymentMethods/PaymentMethods.java

@@ -58,6 +58,12 @@
 @AllArgsConstructor
 public final class PaymentMethods {
 
+    /**
+     * The payment method that automatically confirms the payment when it is ready, for example "card".
+     * [Optional]
+     */
+    private String autoConfirm;
+
     /**
      * Instrument (saved payment source) configuration.
      * [Optional]

src/main/java/com/checkout/handlepaymentsandpayouts/setups/entities/paymentMethods/applepay/ApplePay.java

@@ -3,10 +3,13 @@
 import com.checkout.common.Phone;
 import com.checkout.handlepaymentsandpayouts.setups.entities.paymentMethods.common.CardAccountHolder;
 import com.checkout.handlepaymentsandpayouts.setups.entities.paymentMethods.common.PaymentMethodBase;
+import com.checkout.handlepaymentsandpayouts.setups.entities.paymentMethods.common.PaymentSetupScheme;
+import com.checkout.handlepaymentsandpayouts.setups.entities.paymentMethods.common.WalletToken;
+import com.checkout.payments.PreferredSchema;
 import lombok.Data;
 import lombok.EqualsAndHashCode;
 
-import java.time.Instant;
+import java.util.List;
 
 /**
  * The Apple Pay payment method's details and configuration.
@@ -17,26 +20,20 @@ public final class ApplePay extends PaymentMethodBase {
 
     /**
      * The Apple Pay encrypted payment token data.
-     * [Optional]
+     * [Optional] writeOnly
      */
     private ApplePayTokenData tokenData;
 
     /**
-     * The Apple Pay payment token string.
+     * The Checkout.com Apple Pay token.
      * [Optional]
      */
-    private String token;
+    private WalletToken token;
 
     /**
-     * The date and time the token expires.
-     * [Optional]
-     * Format: date-time (ISO 8601)
-     */
-    private Instant expiresOn;
-
-    /**
-     * Set to true if you intend to reuse the payment credentials in subsequent payments.
-     * [Optional]
+     * Set to true if you intend to reuse the payment credentials in subsequent payments. If set to
+     * false, a payment instrument will not be included in the payment response.
+     * [Optional] writeOnly
      */
     private Boolean storeForFutureUse;
 
@@ -51,4 +48,16 @@ public final class ApplePay extends PaymentMethodBase {
      * [Optional]
      */
     private CardAccountHolder accountHolder;
+
+    /**
+     * The list of supported card scheme names.
+     * [Optional] readOnly
+     */
+    private List<PaymentSetupScheme> schemes;
+
+    /**
+     * The preferred card scheme to process the payment.
+     * [Optional]
+     */
+    private PreferredSchema preferredScheme;
 }

src/main/java/com/checkout/handlepaymentsandpayouts/setups/entities/paymentMethods/card/Card.java

@@ -3,82 +3,37 @@
 import com.checkout.common.Phone;
 import com.checkout.handlepaymentsandpayouts.setups.entities.paymentMethods.common.CardAccountHolder;
 import com.checkout.handlepaymentsandpayouts.setups.entities.paymentMethods.common.PaymentMethodBase;
+import com.checkout.handlepaymentsandpayouts.setups.entities.paymentMethods.common.PaymentSetupScheme;
+import com.checkout.payments.PreferredSchema;
 import lombok.Data;
 import lombok.EqualsAndHashCode;
 
-import java.time.Instant;
+import java.util.List;
 
 /**
- * The Card payment method's details and configuration.
+ * The Card payment method's details and configuration. The card data lives under
+ * {@link #getDetails()}, which maps {@code card.details}.
  */
 @Data
 @EqualsAndHashCode(callSuper = true)
 public final class Card extends PaymentMethodBase {
 
     /**
-     * The card number (without separators). Write-only.
+     * The Checkout.com card token to use instead of the raw card details.
      * [Optional]
      */
-    private String number;
+    private CardToken token;
 
     /**
-     * The last four digits of the card number. Read-only.
+     * The card details.
      * [Optional]
      */
-    private String last4;
+    private CardDetails details;
 
     /**
-     * The card issuer's Bank Identification Number (BIN). Read-only.
-     * [Optional]
-     */
-    private String bin;
-
-    /**
-     * The card scheme. Read-only.
-     * [Optional]
-     */
-    private String scheme;
-
-    /**
-     * The expiry month of the card.
-     * [Optional]
-     */
-    private Integer expiryMonth;
-
-    /**
-     * The expiry year of the card.
-     * [Optional]
-     */
-    private Integer expiryYear;
-
-    /**
-     * The cardholder's name. Write-only.
-     * [Optional]
-     */
-    private String name;
-
-    /**
-     * The card verification value/code. 3 digits, except for American Express (4 digits). Write-only.
-     * [Optional]
-     */
-    private String cvv;
-
-    /**
-     * Set to true for payments that use stored card details. Write-only.
-     * [Optional]
-     */
-    private Boolean stored;
-
-    /**
-     * The time by which the card details must be confirmed. Read-only.
-     * [Optional]
-     * Format: date-time (ISO 8601)
-     */
-    private Instant expiresOn;
-
-    /**
-     * Set to true if you intend to reuse the payment credentials in subsequent payments. Write-only.
-     * [Optional]
+     * Set to true if you intend to reuse the payment credentials in subsequent payments. If set to
+     * false, a payment instrument will not be included in the payment response.
+     * [Optional] writeOnly
      */
     private Boolean storeForFutureUse;
 
@@ -95,8 +50,14 @@ public final class Card extends PaymentMethodBase {
     private CardAccountHolder accountHolder;
 
     /**
-     * Indicates whether to use the Real-Time Account Updater to update the card information.
+     * The list of supported card scheme names.
+     * [Optional] readOnly
+     */
+    private List<PaymentSetupScheme> schemes;
+
+    /**
+     * The preferred card scheme to process the payment.
      * [Optional]
      */
-    private Boolean allowUpdate;
+    private PreferredSchema preferredScheme;
 }

src/main/java/com/checkout/handlepaymentsandpayouts/setups/entities/paymentMethods/card/CardDetails.java

@@ -0,0 +1,87 @@
+package com.checkout.handlepaymentsandpayouts.setups.entities.paymentMethods.card;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.time.Instant;
+
+/**
+ * The card details of the card payment method.
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public final class CardDetails {
+
+    /**
+     * The card number (without separators).
+     * [Optional] writeOnly
+     */
+    private String number;
+
+    /**
+     * The last four digits of the card number.
+     * [Optional] readOnly
+     */
+    private String last4;
+
+    /**
+     * The card issuer's Bank Identification Number (BIN).
+     * [Optional] readOnly
+     */
+    private String bin;
+
+    /**
+     * The card scheme.
+     * [Optional] readOnly
+     */
+    private String scheme;
+
+    /**
+     * The expiry month of the card.
+     * [Optional]
+     */
+    private Integer expiryMonth;
+
+    /**
+     * The expiry year of the card.
+     * [Optional]
+     */
+    private Integer expiryYear;
+
+    /**
+     * The cardholder's name.
+     * [Optional] writeOnly
+     */
+    private String name;
+
+    /**
+     * The card verification value/code. 3 digits, except for American Express (4 digits).
+     * [Optional] writeOnly
+     */
+    private String cvv;
+
+    /**
+     * Indicates whether this card is being submitted from your own stored card-on-file system, rather
+     * than being entered by the customer at the time of payment. Set to true when you provide card
+     * details that you already have on file for the customer.
+     * [Optional] writeOnly
+     */
+    private Boolean stored;
+
+    /**
+     * The time by which the card details must be confirmed.
+     * [Optional] readOnly
+     * Format: date-time (ISO 8601)
+     */
+    private Instant expiresOn;
+
+    /**
+     * Indicates whether to use the Real-Time Account Updater to update the card information.
+     * [Optional]
+     */
+    private Boolean allowUpdate;
+}

src/main/java/com/checkout/handlepaymentsandpayouts/setups/entities/paymentMethods/card/CardToken.java

@@ -0,0 +1,22 @@
+package com.checkout.handlepaymentsandpayouts.setups.entities.paymentMethods.card;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+/**
+ * The Checkout.com card token to use for the card payment method.
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public final class CardToken {
+
+    /**
+     * The Checkout.com card token identifier.
+     * [Optional]
+     */
+    private String id;
+}

src/main/java/com/checkout/handlepaymentsandpayouts/setups/entities/paymentMethods/common/CardAccountHolder.java

@@ -39,7 +39,14 @@ public final class CardAccountHolder {
     private String middleName;
 
     /**
-     * Indicates whether the ANI (account name inquiry) check is performed with the card scheme.
+     * The card account holder's company name.
+     * [Optional]
+     */
+    private String companyName;
+
+    /**
+     * Indicates whether the ANI (account name inquiry) check is performed with the card scheme
+     * (Visa or Mastercard).
      * [Optional]
      */
     private Boolean accountNameInquiry;

src/main/java/com/checkout/handlepaymentsandpayouts/setups/entities/paymentMethods/common/PaymentMethodStatus.java

@@ -22,7 +22,12 @@ public enum PaymentMethodStatus {
 
     /**
      * Not defined by the current API specification. Kept for backward compatibility.
+     *
+     * @deprecated not part of the PaymentMethodStatus enum in the API specification, which lists
+     * unavailable, action_required, ready, initialization_required and invalid. It will be
+     * removed in the next major version.
      */
+    @Deprecated
     @SerializedName("pending")
     PENDING,
 
@@ -34,7 +39,12 @@ public enum PaymentMethodStatus {
 
     /**
      * Not defined by the current API specification. Kept for backward compatibility.
+     *
+     * @deprecated not part of the PaymentMethodStatus enum in the API specification, which lists
+     * unavailable, action_required, ready, initialization_required and invalid. It will be
+     * removed in the next major version.
      */
+    @Deprecated
     @SerializedName("available")
     AVAILABLE,