deprecate(issuing): deprecate the update-card headers and allow revoke and suspend without a body

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

@@ -92,10 +92,44 @@ public interface IssuingClient {
 
     CompletableFuture<CardCredentialsResponse> getCardCredentials(final String cardId, final CardCredentialsQuery queryFilter);
 
+    /**
+     * Revokes a card (POST /issuing/cards/{cardId}/revoke).
+     *
+     * @param cardId the card ID
+     * @param revokeCardRequest the optional request body; when {@code null} no body is sent
+     * @return a {@link CompletableFuture} containing the {@link VoidResponse}
+     */
     CompletableFuture<VoidResponse> revokeCard(final String cardId, final RevokeCardRequest revokeCardRequest);
 
+    /**
+     * Revokes a card without a request body (POST /issuing/cards/{cardId}/revoke).
+     *
+     * @param cardId the card ID
+     * @return a {@link CompletableFuture} containing the {@link VoidResponse}
+     */
+    default CompletableFuture<VoidResponse> revokeCard(String cardId) {
+        return revokeCard(cardId, null);
+    }
+
+    /**
+     * Suspends a card (POST /issuing/cards/{cardId}/suspend).
+     *
+     * @param cardId the card ID
+     * @param suspendCardRequest the optional request body; when {@code null} no body is sent
+     * @return a {@link CompletableFuture} containing the {@link VoidResponse}
+     */
     CompletableFuture<VoidResponse> suspendCard(final String cardId, final SuspendCardRequest suspendCardRequest);
 
+    /**
+     * Suspends a card without a request body (POST /issuing/cards/{cardId}/suspend).
+     *
+     * @param cardId the card ID
+     * @return a {@link CompletableFuture} containing the {@link VoidResponse}
+     */
+    default CompletableFuture<VoidResponse> suspendCard(String cardId) {
+        return suspendCard(cardId, null);
+    }
+
     /**
      * Creates a card control (POST /issuing/controls).
      *
@@ -189,16 +223,17 @@ CompletableFuture<CardAuthorizationReversalResponse> simulateReversal(
     CompletableFuture<UpdateCardResponse> updateCard(final String cardId, final UpdateCardRequest updateCardRequest);
 
     /**
-     * Update a card's details, sending the optional return-encrypted-cvv and Encryption-Key
-     * headers. Set return-encrypted-cvv to true to receive the card's encrypted CVV in the
-     * response; the API returns a 422 with error code encryption_key_required if Encryption-Key
-     * is not also supplied.
+     * Update a card's details, sending the return-encrypted-cvv and Encryption-Key headers.
+     * These headers are no longer documented by the API; they are still sent when set.
      *
      * @param cardId the card ID
      * @param updateCardRequest the card fields to update
      * @param headers the optional return-encrypted-cvv and Encryption-Key headers
      * @return a {@link CompletableFuture} containing the {@link UpdateCardResponse}
+     * @deprecated These headers are no longer documented by the API and are still sent when set; use
+     * {@link #updateCard(String, UpdateCardRequest)} instead. Will be removed in the next major version.
      */
+    @Deprecated
     CompletableFuture<UpdateCardResponse> updateCard(String cardId, UpdateCardRequest updateCardRequest, CardUpdateHeaders headers);
 
     CompletableFuture<RenewCardResponse> renewCard(final String cardId, final RenewCardRequest renewCardRequest);
@@ -266,10 +301,44 @@ CompletableFuture<CardAuthorizationReversalResponse> simulateReversal(
 
     CardCredentialsResponse getCardCredentialsSync(String cardId, CardCredentialsQuery queryFilter);
 
+    /**
+     * Revokes a card (POST /issuing/cards/{cardId}/revoke).
+     *
+     * @param cardId the card ID
+     * @param revokeCardRequest the optional request body; when {@code null} no body is sent
+     * @return the {@link VoidResponse}
+     */
     VoidResponse revokeCardSync(String cardId, RevokeCardRequest revokeCardRequest);
 
+    /**
+     * Revokes a card without a request body (POST /issuing/cards/{cardId}/revoke).
+     *
+     * @param cardId the card ID
+     * @return the {@link VoidResponse}
+     */
+    default VoidResponse revokeCardSync(String cardId) {
+        return revokeCardSync(cardId, null);
+    }
+
+    /**
+     * Suspends a card (POST /issuing/cards/{cardId}/suspend).
+     *
+     * @param cardId the card ID
+     * @param suspendCardRequest the optional request body; when {@code null} no body is sent
+     * @return the {@link VoidResponse}
+     */
     VoidResponse suspendCardSync(String cardId, SuspendCardRequest suspendCardRequest);
 
+    /**
+     * Suspends a card without a request body (POST /issuing/cards/{cardId}/suspend).
+     *
+     * @param cardId the card ID
+     * @return the {@link VoidResponse}
+     */
+    default VoidResponse suspendCardSync(String cardId) {
+        return suspendCardSync(cardId, null);
+    }
+
     /**
      * Creates a card control (POST /issuing/controls).
      *
@@ -363,16 +432,17 @@ CardAuthorizationReversalResponse simulateReversalSync(
     UpdateCardResponse updateCardSync(String cardId, UpdateCardRequest updateCardRequest);
 
     /**
-     * Update a card's details, sending the optional return-encrypted-cvv and Encryption-Key
-     * headers. Set return-encrypted-cvv to true to receive the card's encrypted CVV in the
-     * response; the API returns a 422 with error code encryption_key_required if Encryption-Key
-     * is not also supplied.
+     * Update a card's details, sending the return-encrypted-cvv and Encryption-Key headers.
+     * These headers are no longer documented by the API; they are still sent when set.
      *
      * @param cardId the card ID
      * @param updateCardRequest the card fields to update
      * @param headers the optional return-encrypted-cvv and Encryption-Key headers
      * @return the {@link UpdateCardResponse}
+     * @deprecated These headers are no longer documented by the API and are still sent when set; use
+     * {@link #updateCardSync(String, UpdateCardRequest)} instead. Will be removed in the next major version.
      */
+    @Deprecated
     UpdateCardResponse updateCardSync(String cardId, UpdateCardRequest updateCardRequest, CardUpdateHeaders headers);
 
     RenewCardResponse renewCardSync(String cardId, RenewCardRequest renewCardRequest);

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

@@ -281,7 +281,7 @@ public CompletableFuture<CardCredentialsResponse> getCardCredentials(
 
     @Override
     public CompletableFuture<VoidResponse> revokeCard(final String cardId, final RevokeCardRequest revokeCardRequest) {
-        validateParams("cardId", cardId, "revokeCardRequest", revokeCardRequest);
+        validateParams("cardId", cardId);
         return apiClient.postAsync(
                 buildPath(ISSUING_PATH, CARDS_PATH, cardId, REVOKE_PATH),
                 sdkAuthorization(),
@@ -296,7 +296,7 @@ public CompletableFuture<VoidResponse> suspendCard(
             final String cardId,
             final SuspendCardRequest suspendCardRequest
     ) {
-        validateParams("cardId", cardId, "suspendCardRequest", suspendCardRequest);
+        validateParams("cardId", cardId);
         return apiClient.postAsync(
                 buildPath(ISSUING_PATH, CARDS_PATH, cardId, SUSPEND_PATH),
                 sdkAuthorization(),
@@ -587,16 +587,17 @@ public CompletableFuture<UpdateCardResponse> updateCard(final String cardId, fin
     }
 
     /**
-     * Update a card's details, sending the optional return-encrypted-cvv and Encryption-Key
-     * headers. Set return-encrypted-cvv to true to receive the card's encrypted CVV in the
-     * response; the API returns a 422 with error code encryption_key_required if Encryption-Key
-     * is not also supplied.
+     * Update a card's details, sending the return-encrypted-cvv and Encryption-Key headers.
+     * These headers are no longer documented by the API; they are still sent when set.
      *
      * @param cardId the card ID
      * @param updateCardRequest the card fields to update
      * @param headers the optional return-encrypted-cvv and Encryption-Key headers
      * @return a {@link CompletableFuture} containing the {@link UpdateCardResponse}
+     * @deprecated These headers are no longer documented by the API and are still sent when set; use
+     * {@link #updateCard(String, UpdateCardRequest)} instead. Will be removed in the next major version.
      */
+    @Deprecated
     @Override
     public CompletableFuture<UpdateCardResponse> updateCard(final String cardId, final UpdateCardRequest updateCardRequest,
                                                             final CardUpdateHeaders headers) {
@@ -872,7 +873,7 @@ public CardCredentialsResponse getCardCredentialsSync(
 
     @Override
     public VoidResponse revokeCardSync(final String cardId, final RevokeCardRequest revokeCardRequest) {
-        validateCardIdAndRevokeRequest(cardId, revokeCardRequest);
+        validateParams("cardId", cardId);
         return apiClient.post(
                 buildPath(ISSUING_PATH, CARDS_PATH, cardId, REVOKE_PATH),
                 sdkAuthorization(),
@@ -887,7 +888,7 @@ public VoidResponse suspendCardSync(
             final String cardId,
             final SuspendCardRequest suspendCardRequest
     ) {
-        validateCardIdAndSuspendRequest(cardId, suspendCardRequest);
+        validateParams("cardId", cardId);
         return apiClient.post(
                 buildPath(ISSUING_PATH, CARDS_PATH, cardId, SUSPEND_PATH),
                 sdkAuthorization(),
@@ -1177,16 +1178,17 @@ public UpdateCardResponse updateCardSync(final String cardId, final UpdateCardRe
     }
 
     /**
-     * Update a card's details, sending the optional return-encrypted-cvv and Encryption-Key
-     * headers. Set return-encrypted-cvv to true to receive the card's encrypted CVV in the
-     * response; the API returns a 422 with error code encryption_key_required if Encryption-Key
-     * is not also supplied.
+     * Update a card's details, sending the return-encrypted-cvv and Encryption-Key headers.
+     * These headers are no longer documented by the API; they are still sent when set.
      *
      * @param cardId the card ID
      * @param updateCardRequest the card fields to update
      * @param headers the optional return-encrypted-cvv and Encryption-Key headers
      * @return the {@link UpdateCardResponse}
+     * @deprecated These headers are no longer documented by the API and are still sent when set; use
+     * {@link #updateCardSync(String, UpdateCardRequest)} instead. Will be removed in the next major version.
      */
+    @Deprecated
     @Override
     public UpdateCardResponse updateCardSync(final String cardId, final UpdateCardRequest updateCardRequest,
                                              final CardUpdateHeaders headers) {
@@ -1344,14 +1346,6 @@ private void validateCardIdAndCredentialsQuery(final String cardId, final CardCr
         validateParams("cardId", cardId, "queryFilter", queryFilter);
     }
 
-    private void validateCardIdAndRevokeRequest(final String cardId, final RevokeCardRequest revokeCardRequest) {
-        validateParams("cardId", cardId, "revokeCardRequest", revokeCardRequest);
-    }
-
-    private void validateCardIdAndSuspendRequest(final String cardId, final SuspendCardRequest suspendCardRequest) {
-        validateParams("cardId", cardId, "suspendCardRequest", suspendCardRequest);
-    }
-
     private void validateCardControlRequest(final CardControlRequest cardControlRequest) {
         validateParams("cardControlRequest", cardControlRequest);
     }

src/main/java/com/checkout/issuing/cards/requests/revoke/RevokeCardRequest.java

@@ -3,9 +3,20 @@
 import lombok.Builder;
 import lombok.Data;
 
+/**
+ * The optional request body for POST /issuing/cards/{cardId}/revoke. The body itself is optional:
+ * the client methods accept {@code null} and then send no body.
+ */
 @Data
 @Builder
 public final class RevokeCardRequest {
 
+    /**
+     * The reason why the card is being revoked.
+     * <p>
+     * [Optional]
+     * </p>
+     * Enum: "expired" "reported_lost" "reported_stolen"
+     */
     private RevokeReason reason;
 }

src/main/java/com/checkout/issuing/cards/requests/revoke/RevokeReason.java

@@ -2,6 +2,9 @@
 
 import com.google.gson.annotations.SerializedName;
 
+/**
+ * The reason why the card is being revoked.
+ */
 public enum RevokeReason {
 
     @SerializedName("expired")

src/main/java/com/checkout/issuing/cards/requests/suspend/SuspendCardRequest.java

@@ -3,9 +3,20 @@
 import lombok.Builder;
 import lombok.Data;
 
+/**
+ * The optional request body for POST /issuing/cards/{cardId}/suspend. The body itself is optional:
+ * the client methods accept {@code null} and then send no body.
+ */
 @Data
 @Builder
 public final class SuspendCardRequest {
 
+    /**
+     * The reason why the card is being suspended.
+     * <p>
+     * [Optional]
+     * </p>
+     * Enum: "suspected_lost" "suspected_stolen"
+     */
     private SuspendReason reason;
 }

src/main/java/com/checkout/issuing/cards/requests/suspend/SuspendReason.java

@@ -2,6 +2,9 @@
 
 import com.google.gson.annotations.SerializedName;
 
+/**
+ * The reason why the card is being suspended.
+ */
 public enum SuspendReason {
 
     @SerializedName("suspected_lost")

src/main/java/com/checkout/issuing/cards/requests/update/CardUpdateHeaders.java

@@ -10,29 +10,29 @@
 import java.util.Map;
 
 /**
- * The optional HTTP headers accepted when updating a card's details.
+ * The return-encrypted-cvv and Encryption-Key HTTP headers for updating a card's details
+ * (PATCH /issuing/cards/{cardId}). They are still sent when set.
  *
- * @see <a href="https://api-reference.checkout.com/">PATCH /issuing/cards/{cardId}</a>
+ * @deprecated These headers are no longer documented by the API and are still sent when set;
+ * use the method without headers. Will be removed in the next major version.
  */
+@Deprecated
 @Data
 @Builder
 @NoArgsConstructor
 @AllArgsConstructor
 public class CardUpdateHeaders implements IHeaders {
 
     /**
-     * The return-encrypted-cvv HTTP header. Set to true to retrieve the card's encrypted
-     * credentials in the response. Requires an RSA public key to be provided in the
-     * Encryption-Key header.
+     * The value sent in the return-encrypted-cvv HTTP header. This header is no longer
+     * documented by the API. Still sent when set.
      * [Optional]
      */
     private Boolean returnEncryptedCvv;
 
     /**
-     * The Encryption-Key HTTP header. The RSA public key used to encrypt returned credentials.
-     * Required when the return-encrypted-cvv header is set to true. Provide the public key with
-     * the BEGIN PUBLIC KEY and END PUBLIC KEY headers and any newline characters removed,
-     * encoded as Base64.
+     * The value sent in the Encryption-Key HTTP header. This header is no longer documented
+     * by the API. Still sent when set.
      * [Optional]
      */
     private String encryptionKey;

src/main/java/com/checkout/issuing/cards/responses/update/UpdateCardResponse.java

@@ -17,10 +17,9 @@
 /**
  * Response returned when updating a card.
  * <p>
- * As of the 2026-09-17 API change, {@code update-card-response} is defined as the full
- * {@code get-card-response} field set (see {@link com.checkout.issuing.cards.responses.CardDetailsResponse})
- * with {@code lastModifiedDate} required. It no longer includes {@code encrypted_cvv}: that field
- * was added by the 2026-09-02 change and removed again by this one.
+ * {@code update-card-response} is the full {@code get-card-response} field set (see
+ * {@link com.checkout.issuing.cards.responses.CardDetailsResponse}) with {@code lastModifiedDate}
+ * required. It does not include {@code encrypted_cvv}.
  */
 @Data
 @EqualsAndHashCode(callSuper = true)