fix(issuing): deserialize mid_limit card controls and complete control responses

src/main/java/com/checkout/GsonSerializer.java

@@ -16,6 +16,7 @@
 import com.checkout.issuing.controls.requests.ControlType;
 import com.checkout.issuing.controls.responses.create.CardControlResponse;
 import com.checkout.issuing.controls.responses.create.MccCardControlResponse;
+import com.checkout.issuing.controls.responses.create.MidCardControlResponse;
 import com.checkout.issuing.controls.responses.create.VelocityCardControlResponse;
 import com.checkout.payments.PaymentDestinationType;
 import com.checkout.payments.ProductResponse;
@@ -249,7 +250,8 @@ public final class GsonSerializer implements Serializer {
             // Issuing CS2 - CardControlsResponse
             .registerTypeAdapterFactory(RuntimeTypeAdapterFactory.of(CardControlResponse.class, CheckoutUtils.CONTROL_TYPE, true)
                     .registerSubtype(VelocityCardControlResponse.class, identifier(ControlType.VELOCITY_LIMIT))
-                    .registerSubtype(MccCardControlResponse.class, identifier(ControlType.MCC_LIMIT)))
+                    .registerSubtype(MccCardControlResponse.class, identifier(ControlType.MCC_LIMIT))
+                    .registerSubtype(MidCardControlResponse.class, identifier(ControlType.MID_LIMIT)))
             // Issuing CS2 - ControlGroupControl
             .registerTypeAdapterFactory(RuntimeTypeAdapterFactory.of(com.checkout.issuing.controls.requests.controlgroup.ControlGroupControl.class, CheckoutUtils.CONTROL_TYPE, true)
                     .registerSubtype(com.checkout.issuing.controls.requests.controlgroup.VelocityControlGroupControl.class, identifier(ControlType.VELOCITY_LIMIT))

src/main/java/com/checkout/issuing/IssuingClient.java

@@ -96,14 +96,46 @@ public interface IssuingClient {
 
     CompletableFuture<VoidResponse> suspendCard(final String cardId, final SuspendCardRequest suspendCardRequest);
 
+    /**
+     * Creates a card control (POST /issuing/controls).
+     *
+     * @param cardControlRequest the control to create
+     * @return the created control, a subtype of {@link CardControlResponse} chosen by control_type
+     */
     CompletableFuture<CardControlResponse> createControl(final CardControlRequest cardControlRequest);
 
+    /**
+     * Creates a card control (POST /issuing/controls) with an idempotency key.
+     *
+     * @param cardControlRequest the control to create
+     * @param idempotencyKey the idempotency key
+     * @return the created control, a subtype of {@link CardControlResponse} chosen by control_type
+     */
     CompletableFuture<CardControlResponse> createControl(final CardControlRequest cardControlRequest, final String idempotencyKey);
 
+    /**
+     * Gets the controls applied to a target (GET /issuing/controls).
+     *
+     * @param queryFilter the target filter
+     * @return the list of controls, each a subtype of {@link CardControlResponse}
+     */
     CompletableFuture<CardControlsQueryResponse> getCardControls(final CardControlsQuery queryFilter);
 
+    /**
+     * Gets a card control (GET /issuing/controls/{controlId}).
+     *
+     * @param controlId the control ID
+     * @return the control, a subtype of {@link CardControlResponse} chosen by control_type
+     */
     CompletableFuture<CardControlResponse> getCardControlDetails(final String controlId);
 
+    /**
+     * Updates a card control (PUT /issuing/controls/{controlId}).
+     *
+     * @param controlId the control ID
+     * @param updateCardControlRequest the fields to update
+     * @return the updated control: {@link com.checkout.issuing.controls.responses.create.VelocityCardControlResponse}, {@link com.checkout.issuing.controls.responses.create.MccCardControlResponse} or {@link com.checkout.issuing.controls.responses.create.MidCardControlResponse}, chosen by control_type
+     */
     CompletableFuture<CardControlResponse> updateCardControl(final String controlId, final UpdateCardControlRequest updateCardControlRequest);
 
     CompletableFuture<IdResponse> removeCardControl(final String controlId);
@@ -238,14 +270,46 @@ CompletableFuture<CardAuthorizationReversalResponse> simulateReversal(
 
     VoidResponse suspendCardSync(String cardId, SuspendCardRequest suspendCardRequest);
 
+    /**
+     * Creates a card control (POST /issuing/controls).
+     *
+     * @param cardControlRequest the control to create
+     * @return the created control, a subtype of {@link CardControlResponse} chosen by control_type
+     */
     CardControlResponse createControlSync(CardControlRequest cardControlRequest);
 
+    /**
+     * Creates a card control (POST /issuing/controls) with an idempotency key.
+     *
+     * @param cardControlRequest the control to create
+     * @param idempotencyKey the idempotency key
+     * @return the created control, a subtype of {@link CardControlResponse} chosen by control_type
+     */
     CardControlResponse createControlSync(CardControlRequest cardControlRequest, String idempotencyKey);
 
+    /**
+     * Gets the controls applied to a target (GET /issuing/controls).
+     *
+     * @param queryFilter the target filter
+     * @return the list of controls, each a subtype of {@link CardControlResponse}
+     */
     CardControlsQueryResponse getCardControlsSync(CardControlsQuery queryFilter);
 
+    /**
+     * Gets a card control (GET /issuing/controls/{controlId}).
+     *
+     * @param controlId the control ID
+     * @return the control, a subtype of {@link CardControlResponse} chosen by control_type
+     */
     CardControlResponse getCardControlDetailsSync(String controlId);
 
+    /**
+     * Updates a card control (PUT /issuing/controls/{controlId}).
+     *
+     * @param controlId the control ID
+     * @param updateCardControlRequest the fields to update
+     * @return the updated control: {@link com.checkout.issuing.controls.responses.create.VelocityCardControlResponse}, {@link com.checkout.issuing.controls.responses.create.MccCardControlResponse} or {@link com.checkout.issuing.controls.responses.create.MidCardControlResponse}, chosen by control_type
+     */
     CardControlResponse updateCardControlSync(String controlId, UpdateCardControlRequest updateCardControlRequest);
 
     IdResponse removeCardControlSync(String controlId);

src/main/java/com/checkout/issuing/controls/requests/MccLimit.java

@@ -5,11 +5,23 @@
 
 import java.util.List;
 
+/**
+ * The merchant category code (MCC) rule, which determines the types of businesses transactions can be processed from.
+ */
 @Data
 @Builder
 public final class MccLimit {
 
+    /**
+     * Sets whether to allow or block the list of MCCs supplied.
+     * [Required]
+     * Enum: "allow", "block"
+     */
     private String type;
 
+    /**
+     * The list of MCCs to allow or block transactions from, as 4-digit ISO 18245 codes.
+     * [Required]
+     */
     private List<String> mccList;
 }

src/main/java/com/checkout/issuing/controls/requests/MidLimit.java

@@ -5,11 +5,24 @@
 
 import java.util.List;
 
+/**
+ * The merchant identification (MID) code rule, which determines the merchants from whom transactions can be processed.
+ */
 @Data
 @Builder
 public final class MidLimit {
 
+    /**
+     * Sets whether to allow or block the list of MIDs supplied.
+     * [Required]
+     * Enum: "allow", "block"
+     */
     private String type;
 
+    /**
+     * The list of merchant identification (MID) codes to allow or block transactions from.
+     * [Required]
+     * Each item: 1 to 15 characters, ^[A-Za-z0-9{}\[\] ,+\-=.();'\/&@*]{1,15}$
+     */
     private List<String> midList;
-}
+}

src/main/java/com/checkout/issuing/controls/requests/VelocityLimit.java

@@ -1,19 +1,63 @@
 package com.checkout.issuing.controls.requests;
 
+import lombok.AccessLevel;
 import lombok.Builder;
 import lombok.Data;
+import lombok.Setter;
 
 import java.util.List;
 
+/**
+ * The velocity limit, which determines how much a target card can spend over a given timeframe.
+ * <p>
+ * Used in control requests and, as {@code VelocityLimitWithRemainingAmount}, in control responses.
+ */
 @Data
-@Builder
 public final class VelocityLimit {
 
+    /**
+     * The amount that can be spent, in minor units.
+     * [Required]
+     * int64, minimum 0
+     */
     private Integer amountLimit;
 
+    /**
+     * The period of time over which the specified {@code amount_limit} can be spent.
+     * [Required]
+     */
     private VelocityWindow velocityWindow;
 
+    /**
+     * The list of merchant category codes (MCCs) that the velocity limit applies to, as four-digit ISO 18245 codes.
+     * [Optional]
+     */
     private List<String> mccList;
 
+    /**
+     * The list of merchant identification (MID) codes to allow or block transactions from.
+     * You can provide either {@code mcc_list} or {@code mid_list}, but not both.
+     * [Optional]
+     */
     private List<String> midList;
+
+    /**
+     * The remaining amount that can be spent, in minor units.
+     * [Required] in control responses only. It is read from the API response and is never sent on requests:
+     * it has no builder method and no setter, so it is always null on request bodies.
+     * int64, minimum 0
+     */
+    @Setter(AccessLevel.NONE)
+    private Long amountRemaining;
+
+    @Builder
+    private VelocityLimit(final Integer amountLimit,
+                          final VelocityWindow velocityWindow,
+                          final List<String> mccList,
+                          final List<String> midList) {
+        this.amountLimit = amountLimit;
+        this.velocityWindow = velocityWindow;
+        this.mccList = mccList;
+        this.midList = midList;
+    }
 }

src/main/java/com/checkout/issuing/controls/requests/VelocityWindow.java

@@ -3,9 +3,17 @@
 import lombok.Builder;
 import lombok.Data;
 
+/**
+ * The period of time over which the specified {@code amount_limit} can be spent.
+ */
 @Data
 @Builder
 public final class VelocityWindow {
 
+    /**
+     * The velocity window's unit of time.
+     * [Required]
+     * Enum: "daily", "weekly", "monthly", "all_time"
+     */
     private VelocityWindowType type;
 }

src/main/java/com/checkout/issuing/controls/responses/create/CardControlResponse.java

@@ -8,21 +8,65 @@
 
 import java.time.Instant;
 
+/**
+ * Base card control response, discriminated on {@code control_type}. Returned by create, get, list and update
+ * control operations; see {@link VelocityCardControlResponse}, {@link MccCardControlResponse} and
+ * {@link MidCardControlResponse}.
+ */
 @Data
 @EqualsAndHashCode(callSuper = true)
 @ToString(callSuper = true)
 public abstract class CardControlResponse extends HttpMetadata {
 
+    /**
+     * 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]
+     * Enum: "velocity_limit", "mcc_limit", "mid_limit"
+     */
     private final ControlType controlType;
 
+    /**
+     * The control's unique identifier.
+     * [Required]
+     * 30 characters, ^ctr_[a-z0-9]{26}$
+     */
     private String id;
 
+    /**
+     * A description for the control.
+     * [Optional]
+     * max 256 characters
+     */
     private String description;
 
+    /**
+     * The ID of the card or control profile.
+     * [Required]
+     * 30 characters, ^(crd|cpr)_[a-z0-9]{26}$
+     */
     private String targetId;
 
+    /**
+     * Indicates whether you can change this control. false: an immutable control applied by Checkout.com.
+     * true: you applied this control and can change it.
+     * [Required]
+     */
+    private Boolean isEditable;
+
+    /**
+     * The date and time the control was created, in UTC.
+     * [Required]
+     * format: date-time (UTC)
+     */
     private Instant createdDate;
 
+    /**
+     * The date and time the control was last modified, in UTC.
+     * [Required]
+     * format: date-time (UTC)
+     */
     private Instant lastModifiedDate;
 
     protected CardControlResponse(final ControlType controlType) {

src/main/java/com/checkout/issuing/controls/responses/create/MccCardControlResponse.java

@@ -8,12 +8,19 @@
 import lombok.Setter;
 import lombok.ToString;
 
+/**
+ * Card control response for control_type {@code mcc_limit}.
+ */
 @Getter
 @Setter
 @EqualsAndHashCode(callSuper = true)
 @ToString(callSuper = true)
 public final class MccCardControlResponse extends CardControlResponse {
 
+    /**
+     * The merchant category code (MCC) rule, which determines the types of businesses transactions can be processed from.
+     * [Optional] in the update control response, [Required] in the get control response.
+     */
     private MccLimit mccLimit;
 
     @Builder

src/main/java/com/checkout/issuing/controls/responses/create/MidCardControlResponse.java

@@ -8,12 +8,19 @@
 import lombok.Setter;
 import lombok.ToString;
 
+/**
+ * Card control response for control_type {@code mid_limit}.
+ */
 @Getter
 @Setter
 @EqualsAndHashCode(callSuper = true)
 @ToString(callSuper = true)
 public final class MidCardControlResponse extends CardControlResponse {
 
+    /**
+     * The merchant identification (MID) code rule, which determines the merchants from whom transactions can be processed.
+     * [Optional] in the update control response, [Required] in the get control response.
+     */
     private MidLimit midLimit;
 
     @Builder

src/main/java/com/checkout/issuing/controls/responses/create/VelocityCardControlResponse.java

@@ -8,12 +8,19 @@
 import lombok.Setter;
 import lombok.ToString;
 
+/**
+ * Card control response for control_type {@code velocity_limit}.
+ */
 @Getter
 @Setter
 @EqualsAndHashCode(callSuper = true)
 @ToString(callSuper = true)
 public final class VelocityCardControlResponse extends CardControlResponse {
 
+    /**
+     * The velocity limit, which determines how much a target card can spend over a given timeframe.
+     * [Optional] in the update control response, [Required] in the get control response.
+     */
     private VelocityLimit velocityLimit;
 
     @Builder