chore(api): new PaymentEventType for ACH Returns and small updates to 3DS AuthenticationResult (#478)

- adds `ACH_RETURN_SETTLED` to PaymentEventTypes: https://docs.lithic.com/changelog/january-22-2025
- adds `PENDING_CHALLENGE` and `PENDING_DECISION` to 3DS AuthenticationResult. Updates this field to be required and also adds `challenge_orchestrated_by` property

Author: stainless-app[bot]

lithic-java-core/src/main/kotlin/com/lithic/api/models/AuthenticationRetrieveResponse.kt

@@ -69,6 +69,9 @@ private constructor(
     @JsonProperty("browser")
     @ExcludeMissing
     private val browser: JsonField<Browser> = JsonMissing.of(),
+    @JsonProperty("challenge_orchestrated_by")
+    @ExcludeMissing
+    private val challengeOrchestratedBy: JsonField<ChallengeOrchestratedBy> = JsonMissing.of(),
     @JsonProperty("three_ri_request_type")
     @ExcludeMissing
     private val threeRiRequestType: JsonField<ThreeRiRequestType> = JsonMissing.of(),
@@ -89,8 +92,8 @@ private constructor(
         Optional.ofNullable(accountType.getNullable("account_type"))
 
     /** Indicates the outcome of the 3DS authentication process. */
-    fun authenticationResult(): Optional<AuthenticationResult> =
-        Optional.ofNullable(authenticationResult.getNullable("authentication_result"))
+    fun authenticationResult(): AuthenticationResult =
+        authenticationResult.getRequired("authentication_result")
 
     /**
      * Indicates whether the expiration date provided by the cardholder during checkout matches
@@ -165,6 +168,10 @@ private constructor(
      */
     fun browser(): Optional<Browser> = Optional.ofNullable(browser.getNullable("browser"))
 
+    /** Entity that orchestrates the challenge. */
+    fun challengeOrchestratedBy(): Optional<ChallengeOrchestratedBy> =
+        Optional.ofNullable(challengeOrchestratedBy.getNullable("challenge_orchestrated_by"))
+
     /**
      * Type of 3DS Requestor Initiated (3RI) request i.e., a 3DS authentication that takes place at
      * the initiation of the merchant rather than the cardholder. The most common example of this is
@@ -282,6 +289,11 @@ private constructor(
      */
     @JsonProperty("browser") @ExcludeMissing fun _browser(): JsonField<Browser> = browser
 
+    /** Entity that orchestrates the challenge. */
+    @JsonProperty("challenge_orchestrated_by")
+    @ExcludeMissing
+    fun _challengeOrchestratedBy(): JsonField<ChallengeOrchestratedBy> = challengeOrchestratedBy
+
     /**
      * Type of 3DS Requestor Initiated (3RI) request i.e., a 3DS authentication that takes place at
      * the initiation of the merchant rather than the cardholder. The most common example of this is
@@ -327,6 +339,7 @@ private constructor(
         app().ifPresent { it.validate() }
         authenticationRequestType()
         browser().ifPresent { it.validate() }
+        challengeOrchestratedBy()
         threeRiRequestType()
         transaction().ifPresent { it.validate() }
         validated = true
@@ -361,6 +374,7 @@ private constructor(
         private var authenticationRequestType: JsonField<AuthenticationRequestType> =
             JsonMissing.of()
         private var browser: JsonField<Browser> = JsonMissing.of()
+        private var challengeOrchestratedBy: JsonField<ChallengeOrchestratedBy> = JsonMissing.of()
         private var threeRiRequestType: JsonField<ThreeRiRequestType> = JsonMissing.of()
         private var transaction: JsonField<Transaction> = JsonMissing.of()
         private var additionalProperties: MutableMap<String, JsonValue> = mutableMapOf()
@@ -384,6 +398,7 @@ private constructor(
             app = authenticationRetrieveResponse.app
             authenticationRequestType = authenticationRetrieveResponse.authenticationRequestType
             browser = authenticationRetrieveResponse.browser
+            challengeOrchestratedBy = authenticationRetrieveResponse.challengeOrchestratedBy
             threeRiRequestType = authenticationRetrieveResponse.threeRiRequestType
             transaction = authenticationRetrieveResponse.transaction
             additionalProperties =
@@ -417,12 +432,8 @@ private constructor(
         }
 
         /** Indicates the outcome of the 3DS authentication process. */
-        fun authenticationResult(authenticationResult: AuthenticationResult?) =
-            authenticationResult(JsonField.ofNullable(authenticationResult))
-
-        /** Indicates the outcome of the 3DS authentication process. */
-        fun authenticationResult(authenticationResult: Optional<AuthenticationResult>) =
-            authenticationResult(authenticationResult.orElse(null))
+        fun authenticationResult(authenticationResult: AuthenticationResult) =
+            authenticationResult(JsonField.of(authenticationResult))
 
         /** Indicates the outcome of the 3DS authentication process. */
         fun authenticationResult(authenticationResult: JsonField<AuthenticationResult>) = apply {
@@ -607,6 +618,20 @@ private constructor(
          */
         fun browser(browser: JsonField<Browser>) = apply { this.browser = browser }
 
+        /** Entity that orchestrates the challenge. */
+        fun challengeOrchestratedBy(challengeOrchestratedBy: ChallengeOrchestratedBy?) =
+            challengeOrchestratedBy(JsonField.ofNullable(challengeOrchestratedBy))
+
+        /** Entity that orchestrates the challenge. */
+        fun challengeOrchestratedBy(challengeOrchestratedBy: Optional<ChallengeOrchestratedBy>) =
+            challengeOrchestratedBy(challengeOrchestratedBy.orElse(null))
+
+        /** Entity that orchestrates the challenge. */
+        fun challengeOrchestratedBy(challengeOrchestratedBy: JsonField<ChallengeOrchestratedBy>) =
+            apply {
+                this.challengeOrchestratedBy = challengeOrchestratedBy
+            }
+
         /**
          * Type of 3DS Requestor Initiated (3RI) request i.e., a 3DS authentication that takes place
          * at the initiation of the merchant rather than the cardholder. The most common example of
@@ -695,6 +720,7 @@ private constructor(
                 app,
                 authenticationRequestType,
                 browser,
+                challengeOrchestratedBy,
                 threeRiRequestType,
                 transaction,
                 additionalProperties.toImmutable(),
@@ -828,13 +854,19 @@ private constructor(
 
             @JvmField val SUCCESS = of("SUCCESS")
 
+            @JvmField val PENDING_CHALLENGE = of("PENDING_CHALLENGE")
+
+            @JvmField val PENDING_DECISION = of("PENDING_DECISION")
+
             @JvmStatic fun of(value: String) = AuthenticationResult(JsonField.of(value))
         }
 
         /** An enum containing [AuthenticationResult]'s known values. */
         enum class Known {
             DECLINE,
             SUCCESS,
+            PENDING_CHALLENGE,
+            PENDING_DECISION,
         }
 
         /**
@@ -850,6 +882,8 @@ private constructor(
         enum class Value {
             DECLINE,
             SUCCESS,
+            PENDING_CHALLENGE,
+            PENDING_DECISION,
             /**
              * An enum member indicating that [AuthenticationResult] was instantiated with an
              * unknown value.
@@ -868,6 +902,8 @@ private constructor(
             when (this) {
                 DECLINE -> Value.DECLINE
                 SUCCESS -> Value.SUCCESS
+                PENDING_CHALLENGE -> Value.PENDING_CHALLENGE
+                PENDING_DECISION -> Value.PENDING_DECISION
                 else -> Value._UNKNOWN
             }
 
@@ -884,6 +920,8 @@ private constructor(
             when (this) {
                 DECLINE -> Known.DECLINE
                 SUCCESS -> Known.SUCCESS
+                PENDING_CHALLENGE -> Known.PENDING_CHALLENGE
+                PENDING_DECISION -> Known.PENDING_DECISION
                 else -> throw LithicInvalidDataException("Unknown AuthenticationResult: $value")
             }
 
@@ -4200,6 +4238,110 @@ private constructor(
             "Browser{ip=$ip, javaEnabled=$javaEnabled, javascriptEnabled=$javascriptEnabled, language=$language, timeZone=$timeZone, userAgent=$userAgent, additionalProperties=$additionalProperties}"
     }
 
+    /** Entity that orchestrates the challenge. */
+    class ChallengeOrchestratedBy
+    @JsonCreator
+    private constructor(
+        private val value: JsonField<String>,
+    ) : Enum {
+
+        /**
+         * Returns this class instance's raw value.
+         *
+         * This is usually only useful if this instance was deserialized from data that doesn't
+         * match any known member, and you want to know that value. For example, if the SDK is on an
+         * older version than the API, then the API may respond with new members that the SDK is
+         * unaware of.
+         */
+        @com.fasterxml.jackson.annotation.JsonValue fun _value(): JsonField<String> = value
+
+        companion object {
+
+            @JvmField val LITHIC = of("LITHIC")
+
+            @JvmField val CUSTOMER = of("CUSTOMER")
+
+            @JvmField val NO_CHALLENGE = of("NO_CHALLENGE")
+
+            @JvmStatic fun of(value: String) = ChallengeOrchestratedBy(JsonField.of(value))
+        }
+
+        /** An enum containing [ChallengeOrchestratedBy]'s known values. */
+        enum class Known {
+            LITHIC,
+            CUSTOMER,
+            NO_CHALLENGE,
+        }
+
+        /**
+         * An enum containing [ChallengeOrchestratedBy]'s known values, as well as an [_UNKNOWN]
+         * member.
+         *
+         * An instance of [ChallengeOrchestratedBy] can contain an unknown value in a couple of
+         * cases:
+         * - It was deserialized from data that doesn't match any known member. For example, if the
+         *   SDK is on an older version than the API, then the API may respond with new members that
+         *   the SDK is unaware of.
+         * - It was constructed with an arbitrary value using the [of] method.
+         */
+        enum class Value {
+            LITHIC,
+            CUSTOMER,
+            NO_CHALLENGE,
+            /**
+             * An enum member indicating that [ChallengeOrchestratedBy] was instantiated with an
+             * unknown value.
+             */
+            _UNKNOWN,
+        }
+
+        /**
+         * Returns an enum member corresponding to this class instance's value, or [Value._UNKNOWN]
+         * if the class was instantiated with an unknown value.
+         *
+         * Use the [known] method instead if you're certain the value is always known or if you want
+         * to throw for the unknown case.
+         */
+        fun value(): Value =
+            when (this) {
+                LITHIC -> Value.LITHIC
+                CUSTOMER -> Value.CUSTOMER
+                NO_CHALLENGE -> Value.NO_CHALLENGE
+                else -> Value._UNKNOWN
+            }
+
+        /**
+         * Returns an enum member corresponding to this class instance's value.
+         *
+         * Use the [value] method instead if you're uncertain the value is always known and don't
+         * want to throw for the unknown case.
+         *
+         * @throws LithicInvalidDataException if this class instance's value is a not a known
+         *   member.
+         */
+        fun known(): Known =
+            when (this) {
+                LITHIC -> Known.LITHIC
+                CUSTOMER -> Known.CUSTOMER
+                NO_CHALLENGE -> Known.NO_CHALLENGE
+                else -> throw LithicInvalidDataException("Unknown ChallengeOrchestratedBy: $value")
+            }
+
+        fun asString(): String = _value().asStringOrThrow()
+
+        override fun equals(other: Any?): Boolean {
+            if (this === other) {
+                return true
+            }
+
+            return /* spotless:off */ other is ChallengeOrchestratedBy && value == other.value /* spotless:on */
+        }
+
+        override fun hashCode() = value.hashCode()
+
+        override fun toString() = value.toString()
+    }
+
     /**
      * Type of 3DS Requestor Initiated (3RI) request i.e., a 3DS authentication that takes place at
      * the initiation of the merchant rather than the cardholder. The most common example of this is
@@ -4744,15 +4886,15 @@ private constructor(
             return true
         }
 
-        return /* spotless:off */ other is AuthenticationRetrieveResponse && token == other.token && accountType == other.accountType && authenticationResult == other.authenticationResult && cardExpiryCheck == other.cardExpiryCheck && cardToken == other.cardToken && cardholder == other.cardholder && channel == other.channel && created == other.created && decisionMadeBy == other.decisionMadeBy && merchant == other.merchant && messageCategory == other.messageCategory && threeDSRequestorChallengeIndicator == other.threeDSRequestorChallengeIndicator && additionalData == other.additionalData && app == other.app && authenticationRequestType == other.authenticationRequestType && browser == other.browser && threeRiRequestType == other.threeRiRequestType && transaction == other.transaction && additionalProperties == other.additionalProperties /* spotless:on */
+        return /* spotless:off */ other is AuthenticationRetrieveResponse && token == other.token && accountType == other.accountType && authenticationResult == other.authenticationResult && cardExpiryCheck == other.cardExpiryCheck && cardToken == other.cardToken && cardholder == other.cardholder && channel == other.channel && created == other.created && decisionMadeBy == other.decisionMadeBy && merchant == other.merchant && messageCategory == other.messageCategory && threeDSRequestorChallengeIndicator == other.threeDSRequestorChallengeIndicator && additionalData == other.additionalData && app == other.app && authenticationRequestType == other.authenticationRequestType && browser == other.browser && challengeOrchestratedBy == other.challengeOrchestratedBy && threeRiRequestType == other.threeRiRequestType && transaction == other.transaction && additionalProperties == other.additionalProperties /* spotless:on */
     }
 
     /* spotless:off */
-    private val hashCode: Int by lazy { Objects.hash(token, accountType, authenticationResult, cardExpiryCheck, cardToken, cardholder, channel, created, decisionMadeBy, merchant, messageCategory, threeDSRequestorChallengeIndicator, additionalData, app, authenticationRequestType, browser, threeRiRequestType, transaction, additionalProperties) }
+    private val hashCode: Int by lazy { Objects.hash(token, accountType, authenticationResult, cardExpiryCheck, cardToken, cardholder, channel, created, decisionMadeBy, merchant, messageCategory, threeDSRequestorChallengeIndicator, additionalData, app, authenticationRequestType, browser, challengeOrchestratedBy, threeRiRequestType, transaction, additionalProperties) }
     /* spotless:on */
 
     override fun hashCode(): Int = hashCode
 
     override fun toString() =
-        "AuthenticationRetrieveResponse{token=$token, accountType=$accountType, authenticationResult=$authenticationResult, cardExpiryCheck=$cardExpiryCheck, cardToken=$cardToken, cardholder=$cardholder, channel=$channel, created=$created, decisionMadeBy=$decisionMadeBy, merchant=$merchant, messageCategory=$messageCategory, threeDSRequestorChallengeIndicator=$threeDSRequestorChallengeIndicator, additionalData=$additionalData, app=$app, authenticationRequestType=$authenticationRequestType, browser=$browser, threeRiRequestType=$threeRiRequestType, transaction=$transaction, additionalProperties=$additionalProperties}"
+        "AuthenticationRetrieveResponse{token=$token, accountType=$accountType, authenticationResult=$authenticationResult, cardExpiryCheck=$cardExpiryCheck, cardToken=$cardToken, cardholder=$cardholder, channel=$channel, created=$created, decisionMadeBy=$decisionMadeBy, merchant=$merchant, messageCategory=$messageCategory, threeDSRequestorChallengeIndicator=$threeDSRequestorChallengeIndicator, additionalData=$additionalData, app=$app, authenticationRequestType=$authenticationRequestType, browser=$browser, challengeOrchestratedBy=$challengeOrchestratedBy, threeRiRequestType=$threeRiRequestType, transaction=$transaction, additionalProperties=$additionalProperties}"
 }

lithic-java-core/src/main/kotlin/com/lithic/api/models/FinancialTransaction.kt

@@ -840,6 +840,8 @@ private constructor(
 
                 @JvmField val ACH_RETURN_PROCESSED = of("ACH_RETURN_PROCESSED")
 
+                @JvmField val ACH_RETURN_SETTLED = of("ACH_RETURN_SETTLED")
+
                 @JvmField val AUTHORIZATION = of("AUTHORIZATION")
 
                 @JvmField val AUTHORIZATION_ADVICE = of("AUTHORIZATION_ADVICE")
@@ -959,6 +961,7 @@ private constructor(
                 ACH_RECEIPT_SETTLED,
                 ACH_RETURN_INITIATED,
                 ACH_RETURN_PROCESSED,
+                ACH_RETURN_SETTLED,
                 AUTHORIZATION,
                 AUTHORIZATION_ADVICE,
                 AUTHORIZATION_EXPIRY,
@@ -1035,6 +1038,7 @@ private constructor(
                 ACH_RECEIPT_SETTLED,
                 ACH_RETURN_INITIATED,
                 ACH_RETURN_PROCESSED,
+                ACH_RETURN_SETTLED,
                 AUTHORIZATION,
                 AUTHORIZATION_ADVICE,
                 AUTHORIZATION_EXPIRY,
@@ -1113,6 +1117,7 @@ private constructor(
                     ACH_RECEIPT_SETTLED -> Value.ACH_RECEIPT_SETTLED
                     ACH_RETURN_INITIATED -> Value.ACH_RETURN_INITIATED
                     ACH_RETURN_PROCESSED -> Value.ACH_RETURN_PROCESSED
+                    ACH_RETURN_SETTLED -> Value.ACH_RETURN_SETTLED
                     AUTHORIZATION -> Value.AUTHORIZATION
                     AUTHORIZATION_ADVICE -> Value.AUTHORIZATION_ADVICE
                     AUTHORIZATION_EXPIRY -> Value.AUTHORIZATION_EXPIRY
@@ -1189,6 +1194,7 @@ private constructor(
                     ACH_RECEIPT_SETTLED -> Known.ACH_RECEIPT_SETTLED
                     ACH_RETURN_INITIATED -> Known.ACH_RETURN_INITIATED
                     ACH_RETURN_PROCESSED -> Known.ACH_RETURN_PROCESSED
+                    ACH_RETURN_SETTLED -> Known.ACH_RETURN_SETTLED
                     AUTHORIZATION -> Known.AUTHORIZATION
                     AUTHORIZATION_ADVICE -> Known.AUTHORIZATION_ADVICE
                     AUTHORIZATION_EXPIRY -> Known.AUTHORIZATION_EXPIRY