fix(issuing): map mid_limit and complete card control and card create responses

src/CheckoutSdk/Issuing/Cards/Responses/Create/AbstractCardControlsResponse.cs

@@ -1,24 +1,68 @@
 using Checkout.Issuing.Common;
+using System;
 
 namespace Checkout.Issuing.Cards.Responses.Create
 {
+    /// <summary>
+    /// A control that was set on the card when the virtual card was created, discriminated on control_type.
+    /// </summary>
     public abstract class AbstractCardControlsResponse
     {
+        /// <summary>
+        /// The control's type.
+        /// A velocity_limit determines how much can be spent over a given period of time. An mcc_limit determines
+        /// the types of businesses from which transactions can be processed. A mid_limit specifies the merchants
+        /// from whom transactions can be processed.
+        /// [Required]
+        /// </summary>
         public IssuingControlType? ControlType { get; set; }
 
+        /// <summary>
+        /// The control's unique identifier.
+        /// [Required]
+        /// ^ctr_[a-z0-9]{26}$
+        /// 30 characters
+        /// </summary>
         public string Id { get; set; }
 
+        /// <summary>
+        /// The ID of the card the control applies to.
+        /// Not returned by the API in this response; still deserialized if present, otherwise null.
+        /// [Optional]
+        /// </summary>
+        [Obsolete("Not returned by the API in this response. Will be removed in the next major version.")]
         public string TargetId { get; set; }
 
+        /// <summary>
+        /// A description for the control.
+        /// [Required]
+        /// max 256 characters
+        /// </summary>
         public string Description { get; set; }
 
+        /// <summary>
+        /// The date and time the control was created.
+        /// Not returned by the API in this response; still deserialized if present, otherwise null.
+        /// [Optional]
+        /// </summary>
+        [Obsolete("Not returned by the API in this response. Will be removed in the next major version.")]
         public string CreatedDate { get; set; }
 
+        /// <summary>
+        /// The date and time the control was last modified.
+        /// Not returned by the API in this response; still deserialized if present, otherwise null.
+        /// [Optional]
+        /// </summary>
+        [Obsolete("Not returned by the API in this response. Will be removed in the next major version.")]
         public string LastModifiedDate { get; set; }
 
+        /// <summary>
+        /// Initializes the control with its discriminator value.
+        /// </summary>
+        /// <param name="controlType">The control's type.</param>
         protected AbstractCardControlsResponse(IssuingControlType controlType)
         {
             ControlType = controlType;
         }
     }
-}
+}

src/CheckoutSdk/Issuing/Cards/Responses/Create/AbstractCardCreateResponse.cs

@@ -4,6 +4,10 @@
 
 namespace Checkout.Issuing.Cards.Responses.Create
 {
+    /// <summary>
+    /// The response returned when a card is created, discriminated on type (virtual or physical).
+    /// _links (CardLinks: self, credentials, revoke, controls and more) is exposed through Links.
+    /// </summary>
     public abstract class AbstractCardCreateResponse : Resource
     {
         /// <summary>
@@ -16,23 +20,23 @@ public abstract class AbstractCardCreateResponse : Resource
         /// The card's unique identifier.
         /// [Required]
         /// ^crd_[a-z0-9]{26}$
-        /// min 30 characters, max 30 characters
+        /// 30 characters
         /// </summary>
         public string Id { get; set; }
 
         /// <summary>
         /// The client's unique identifier.
         /// [Required]
         /// ^cli_[a-z0-9]{26}$
-        /// min 30 characters, max 30 characters
+        /// 30 characters
         /// </summary>
         public string ClientId { get; set; }
 
         /// <summary>
         /// The entity's unique identifier.
         /// [Required]
         /// ^ent_[a-z0-9]{26}$
-        /// min 30 characters, max 30 characters
+        /// 30 characters
         /// </summary>
         public string EntityId { get; set; }
 
@@ -48,62 +52,75 @@ public abstract class AbstractCardCreateResponse : Resource
         /// The last four digits of the card number, also known as the PAN.
         /// [Required]
         /// ^[0-9]{4}$
+        /// 4 characters
         /// </summary>
         public string LastFour { get; set; }
 
         /// <summary>
         /// The card's expiration month.
         /// [Required]
-        /// &gt;= 1
-        /// &lt;= 12
+        /// Format: int32
+        /// min 1, max 12
         /// </summary>
         public int? ExpiryMonth { get; set; }
 
         /// <summary>
         /// The card's expiration year.
         /// [Required]
-        /// min 4 characters, max 4 characters
+        /// Format: int32
+        /// 4 digits
         /// </summary>
         public int? ExpiryYear { get; set; }
 
         /// <summary>
         /// The issuing currency, as a three-letter ISO currency code.
         /// [Required]
+        /// Format: ISO4217
         /// ^[a-zA-Z]{3}$
-        /// min 3 characters, max 3 characters
+        /// 3 characters
         /// </summary>
         public Currency? BillingCurrency { get; set; }
 
         /// <summary>
         /// The issuing country, as a two-letter ISO country code.
         /// [Required]
-        /// min 2 characters, max 2 characters
+        /// 2 characters
         /// </summary>
         public CountryCode? IssuingCountry { get; set; }
 
         /// <summary>
-        /// The date and time the card was created, in UTC.
-        /// [Optional]
+        /// The card scheme.
+        /// [Required]
+        /// </summary>
+        public IssuingScheme? Scheme { get; set; }
+
+        /// <summary>
+        /// The date and time the card was created.
+        /// [Required]
         /// Format: date-time (RFC 3339)
         /// </summary>
         public DateTime? CreatedDate { get; set; }
 
         /// <summary>
         /// The card's status, which determines whether it can approve incoming authorizations.
+        /// inactive: the default state, authorizations are declined until the card is activated.
+        /// active: authorization requests can be approved.
+        /// suspended: authorization requests are declined; the card can be reactivated.
+        /// revoked: authorization requests are permanently declined; the card cannot be reactivated.
         /// [Required]
-        /// Enum: "active" "inactive" "revoked" "suspended"
         /// </summary>
         public CardStatus? Status { get; set; }
 
         /// <summary>
         /// Your reference.
         /// [Optional]
-        /// &lt;= 256 characters
+        /// max 256 characters
         /// </summary>
         public string Reference { get; set; }
 
         /// <summary>
         /// The card will be revoked at midnight UTC on the date specified.
+        /// Not listed in add-card-response, but sent on add-card-request and returned by get-card-response.
         /// [Optional]
         /// Format: yyyy-MM-dd
         /// </summary>
@@ -112,14 +129,19 @@ public abstract class AbstractCardCreateResponse : Resource
         /// <summary>
         /// The date and time the card was last activated. If the card has never been activated, this field
         /// returns null.
-        /// [Optional, read-only]
+        /// [Optional]
         /// Format: date-time (RFC 3339)
+        /// Nullable, read-only
         /// </summary>
         public DateTime? LastActivatedOn { get; set; }
 
+        /// <summary>
+        /// Initializes the card response with its discriminator value.
+        /// </summary>
+        /// <param name="type">The card type.</param>
         protected AbstractCardCreateResponse(IssuingCardType? type)
         {
             Type = type;
         }
     }
-}
+}

src/CheckoutSdk/Issuing/Cards/Responses/Create/CardControlsResponseConverter.cs

@@ -68,7 +68,9 @@ private static AbstractCardControlsResponse Create(string type)
 
         private static string GetSourceType(JToken jObject)
         {
-            return jObject.SelectToken(CheckoutUtils.Type)?.Value<string>()?.ToLowerInvariant();
+            // The spec discriminates card controls on control_type; type is kept as a fallback.
+            var token = jObject.SelectToken(CheckoutUtils.ControlType) ?? jObject.SelectToken(CheckoutUtils.Type);
+            return token?.Value<string>()?.ToLowerInvariant();
         }
     }
 }

src/CheckoutSdk/Issuing/Cards/Responses/Create/Credentials.cs

@@ -1,9 +1,25 @@
 namespace Checkout.Issuing.Cards.Responses.Create
 {
+    /// <summary>
+    /// The virtual card's credentials, returned when they were requested on creation.
+    /// </summary>
     public class Credentials
     {
+        /// <summary>
+        /// The unencrypted card number.
+        /// [Optional]
+        /// Format: pan
+        /// ^[0-9]{16}$
+        /// 16 characters
+        /// </summary>
         public string Number { get; set; }
-
+
+        /// <summary>
+        /// The card's verification code, also known as the CVV or CVC2.
+        /// [Optional]
+        /// ^[0-9]{3}$
+        /// 3 characters
+        /// </summary>
         public string Cvc2 { get; set; }
     }
-}
+}

src/CheckoutSdk/Issuing/Cards/Responses/Create/MccCardControlsResponse.cs

@@ -2,12 +2,23 @@
 
 namespace Checkout.Issuing.Cards.Responses.Create
 {
+    /// <summary>
+    /// A card control of type mcc_limit set when the virtual card was created.
+    /// </summary>
     public class MccCardControlsResponse : AbstractCardControlsResponse
     {
+        /// <summary>
+        /// Initializes an mcc_limit control.
+        /// </summary>
         public MccCardControlsResponse() : base(IssuingControlType.MccLimit)
         {
         }
 
+        /// <summary>
+        /// The merchant category code (MCC) rule, which determines the types of businesses transactions can be
+        /// processed from.
+        /// [Required]
+        /// </summary>
         public MccLimit MccLimit { get; set; }
     }
-}
+}

src/CheckoutSdk/Issuing/Cards/Responses/Create/MidCardControlsResponse.cs

@@ -1,13 +1,39 @@
 using Checkout.Issuing.Common;
+using Newtonsoft.Json;
+using System;
 
 namespace Checkout.Issuing.Cards.Responses.Create
 {
+    /// <summary>
+    /// A card control of type mid_limit set when the virtual card was created.
+    /// </summary>
     public class MidCardControlsResponse : AbstractCardControlsResponse
     {
+        /// <summary>
+        /// Initializes a mid_limit control.
+        /// </summary>
         public MidCardControlsResponse() : base(IssuingControlType.MidLimit)
         {
         }
 
-        public MidLimit VelocityLimit { get; set; }
+        /// <summary>
+        /// The merchant identification (MID) code rule, which determines the merchants from whom transactions can
+        /// be processed.
+        /// [Required]
+        /// </summary>
+        public MidLimit MidLimit { get; set; }
+
+        /// <summary>
+        /// Former name of <see cref="MidLimit"/>. It was mapped to velocity_limit, so it was never populated.
+        /// It now reads and writes <see cref="MidLimit"/> and is not serialized.
+        /// [Optional]
+        /// </summary>
+        [Obsolete("Use MidLimit instead. Will be removed in the next major version.")]
+        [JsonIgnore]
+        public MidLimit VelocityLimit
+        {
+            get => MidLimit;
+            set => MidLimit = value;
+        }
     }
-}
+}

src/CheckoutSdk/Issuing/Cards/Responses/Create/PhysicalCardCreateResponse.cs

@@ -2,10 +2,16 @@
 
 namespace Checkout.Issuing.Cards.Responses.Create
 {
+    /// <summary>
+    /// The response returned when a physical card is created (add-physical-card-response).
+    /// </summary>
     public class PhysicalCardCreateResponse : AbstractCardCreateResponse
     {
+        /// <summary>
+        /// Initializes a physical card response.
+        /// </summary>
         public PhysicalCardCreateResponse() : base(IssuingCardType.Physical)
         {
         }
     }
-}
+}

src/CheckoutSdk/Issuing/Cards/Responses/Create/VelocityCardControlsResponse.cs

@@ -2,12 +2,22 @@
 
 namespace Checkout.Issuing.Cards.Responses.Create
 {
+    /// <summary>
+    /// A card control of type velocity_limit set when the virtual card was created.
+    /// </summary>
     public class VelocityCardControlsResponse : AbstractCardControlsResponse
     {
+        /// <summary>
+        /// Initializes a velocity_limit control.
+        /// </summary>
         public VelocityCardControlsResponse() : base(IssuingControlType.VelocityLimit)
         {
         }
 
+        /// <summary>
+        /// The velocity limit, which determines how much a target card can spend over a given timeframe.
+        /// [Required]
+        /// </summary>
         public VelocityLimit VelocityLimit { get; set; }
     }
-}
+}