feature/INT-1667 - ChallengeIndicator/SessionChallengeIndicator enum alignment

src/main/java/com/checkout/common/ChallengeIndicator.java

@@ -3,52 +3,99 @@
 import com.google.gson.annotations.SerializedName;
 
 /**
- * Indicates whether a challenge is requested for an authentication.
+ * Indicates the preference for whether or not a 3DS challenge should be performed. The customer's
+ * bank has the final say on whether or not the customer receives the challenge.
  * <p>
- * The first four values are valid for all endpoints that accept a challenge indicator
- * (e.g. {@code POST /payments} {@code three_ds.challenge_indicator}, {@code POST /sessions},
- * and their responses).
+ * This is the four-value indicator accepted by the {@code 3ds.challenge_indicator} field on
+ * {@code POST /payments}, {@code POST /hosted-payments}, {@code POST /payment-links} and
+ * {@code POST /payment-sessions}.
  * <p>
- * The remaining values ({@link #LOW_VALUE}, {@link #TRUSTED_LISTING},
- * {@link #TRUSTED_LISTING_PROMPT}, {@link #TRANSACTION_RISK_ASSESSMENT}, {@link #DATA_SHARE})
- * represent requests for exemption and are only valid for {@code POST /sessions}
- * (3DS Standalone Authentication). If an exemption cannot be applied, the value
- * {@link #NO_CHALLENGE_REQUESTED} will be used instead.
+ * [Optional]
+ * <p>
+ * Default: {@link #NO_PREFERENCE}
+ *
+ * @see com.checkout.sessions.SessionChallengeIndicator the wider nine-value enum accepted by
+ * {@code POST /sessions}, which additionally supports requests for exemption
  */
 public enum ChallengeIndicator {
 
+    /**
+     * A challenge is requested for this payment.
+     */
     @SerializedName("challenge_requested")
     CHALLENGE_REQUESTED,
+
+    /**
+     * A challenge is requested for this payment because it is mandated by local regulation or
+     * scheme rules.
+     */
     @SerializedName("challenge_requested_mandate")
     CHALLENGE_REQUESTED_MANDATE,
+
+    /**
+     * A challenge is not requested for this payment.
+     */
     @SerializedName("no_challenge_requested")
     NO_CHALLENGE_REQUESTED,
+
+    /**
+     * No preference as to whether a challenge should be performed. This is the default.
+     */
     @SerializedName("no_preference")
     NO_PREFERENCE,
+
     /**
-     * Request a low-value exemption. Only valid for {@code POST /sessions}.
+     * Request a low-value exemption.
+     *
+     * @deprecated only valid for {@code POST /sessions}, which is now modelled by
+     * {@link com.checkout.sessions.SessionChallengeIndicator#LOW_VALUE}. This value is rejected by
+     * the {@code 3ds.challenge_indicator} fields that use this enum.
      */
+    @Deprecated
     @SerializedName("low_value")
     LOW_VALUE,
+
     /**
-     * Request a trusted listing exemption. Only valid for {@code POST /sessions}.
+     * Request a trusted listing exemption.
+     *
+     * @deprecated only valid for {@code POST /sessions}, which is now modelled by
+     * {@link com.checkout.sessions.SessionChallengeIndicator#TRUSTED_LISTING}. This value is
+     * rejected by the {@code 3ds.challenge_indicator} fields that use this enum.
      */
+    @Deprecated
     @SerializedName("trusted_listing")
     TRUSTED_LISTING,
+
     /**
      * Request a trusted listing prompt to add the merchant to the cardholder's trusted list.
-     * Only valid for {@code POST /sessions}.
+     *
+     * @deprecated only valid for {@code POST /sessions}, which is now modelled by
+     * {@link com.checkout.sessions.SessionChallengeIndicator#TRUSTED_LISTING_PROMPT}. This value is
+     * rejected by the {@code 3ds.challenge_indicator} fields that use this enum.
      */
+    @Deprecated
     @SerializedName("trusted_listing_prompt")
     TRUSTED_LISTING_PROMPT,
+
     /**
-     * Request a transaction risk analysis (TRA) exemption. Only valid for {@code POST /sessions}.
+     * Request a transaction risk analysis (TRA) exemption.
+     *
+     * @deprecated only valid for {@code POST /sessions}, which is now modelled by
+     * {@link com.checkout.sessions.SessionChallengeIndicator#TRANSACTION_RISK_ASSESSMENT}. This
+     * value is rejected by the {@code 3ds.challenge_indicator} fields that use this enum.
      */
+    @Deprecated
     @SerializedName("transaction_risk_assessment")
     TRANSACTION_RISK_ASSESSMENT,
+
     /**
-     * Indicates a data-share authentication request. Only valid for {@code POST /sessions}.
+     * Indicates a data-share authentication request.
+     *
+     * @deprecated only valid for {@code POST /sessions}, which is now modelled by
+     * {@link com.checkout.sessions.SessionChallengeIndicator#DATA_SHARE}. This value is rejected by
+     * the {@code 3ds.challenge_indicator} fields that use this enum.
      */
+    @Deprecated
     @SerializedName("data_share")
     DATA_SHARE,
 

src/main/java/com/checkout/sessions/CreateSessionAcceptedResponse.java

@@ -1,6 +1,5 @@
 package com.checkout.sessions;
 
-import com.checkout.common.ChallengeIndicator;
 import com.checkout.common.Currency;
 import com.checkout.common.Resource;
 import lombok.Data;
@@ -15,48 +14,165 @@
 @ToString(callSuper = true)
 public final class CreateSessionAcceptedResponse extends Resource {
 
+    /**
+     * Session unique identifier.
+     * [Required]
+     * ^(sid)_(\w{26})$
+     * min 30 characters
+     * max 30 characters
+     */
     private String id;
 
+    /**
+     * A base64 encoded value prefixed with {@code sek_} that gives access to client-side operations
+     * for a single authentication within the Sessions API.
+     * [Required]
+     * ^(sek)_(.{44})$
+     * min 48 characters
+     * max 48 characters
+     */
     private String sessionSecret;
 
+    /**
+     * The transaction identifier that needs to be provided when communicating directly with the
+     * Access Control Server (ACS).
+     * [Required]
+     * min 36 characters
+     * max 36 characters
+     */
     private String transactionId;
 
+    /**
+     * Indicates the scheme this authentication is carried out against.
+     * [Required]
+     */
     private SessionScheme scheme;
 
+    /**
+     * The amount in the minor currency.
+     * [Required]
+     * min 0
+     * max 9007199254740991
+     */
     private Long amount;
 
+    /**
+     * The three-letter ISO currency code.
+     * [Required]
+     */
     private Currency currency;
 
+    /**
+     * Indicates the type of payment this session is for. Please note the spelling of
+     * {@code installment} consists of two {@code l}s.
+     * [Required]
+     */
     private AuthenticationType authenticationType;
 
+    /**
+     * Indicates the category of the authentication request.
+     * [Required]
+     */
     private Category authenticationCategory;
 
+    /**
+     * The status of the session.
+     * [Required]
+     */
     private SessionStatus status;
 
+    /**
+     * When the session is unavailable, this points to the reason why.
+     * <p>
+     * Note: this field is not present in the {@code CreateSessionAcceptedResponse} schema of the
+     * Checkout.com API Reference, where it appears only on {@code GET /sessions/{id}}. It is
+     * retained for backwards compatibility pending confirmation from the API owners.
+     * [Optional]
+     */
     private StatusReason statusReason;
 
+    /**
+     * Specifies which action to take in order to complete the session.
+     * The {@code redirect_cardholder} action is only applicable for hosted sessions.
+     * [Required]
+     */
     private List<NextAction> nextActions;
 
+    /**
+     * The protocol version number of the specification used by the API for authentication.
+     * [Required]
+     * max 50 characters
+     */
     private String protocolVersion;
 
+    /**
+     * Additional information about the cardholder's account.
+     * [Optional]
+     */
     private CardholderAccountInfo accountInfo;
 
+    /**
+     * Additional information about the cardholder's purchase.
+     * [Optional]
+     */
     private MerchantRiskInfo merchantRiskInfo;
 
+    /**
+     * A reference you can later use to identify this payment, such as an order number.
+     * [Optional]
+     * max 100 characters
+     */
     private String reference;
 
+    /**
+     * Details related to the session source. This property should always be in the response, unless
+     * a {@code card} source was used and communication with Checkout.com's Vault was not possible.
+     * [Optional]
+     */
     private CardInfo card;
 
+    /**
+     * Details of a recurring authentication.
+     * [Optional]
+     */
     private Recurring recurring;
 
+    /**
+     * Details of an installment authentication.
+     * [Optional]
+     */
     private Installment installment;
 
+    /**
+     * Details of a previous transaction.
+     * [Optional]
+     */
     private InitialTransaction initialTransaction;
 
+    /**
+     * Authentication date and time.
+     * [Required]
+     * Format: date-time (RFC 3339)
+     */
     private Instant authenticationDate;
 
-    private ChallengeIndicator challengeIndicator;
-
+    /**
+     * Indicates the preference for whether or not a 3DS challenge should be performed. The
+     * customer's bank has the final say on whether or not the customer receives the challenge.
+     * <p>
+     * Note: the API Reference specifies only the four base values for this response field, but the
+     * request accepts nine. This is typed as {@link SessionChallengeIndicator} so that an exemption
+     * value echoed back by the API still deserializes; see
+     * {@link SessionRequest#getChallengeIndicator()}.
+     * [Required]
+     * Default: {@link SessionChallengeIndicator#NO_PREFERENCE}
+     */
+    private SessionChallengeIndicator challengeIndicator;
+
+    /**
+     * The information about the optimization options selected.
+     * [Optional]
+     */
     private Optimization optimization;
 
 }