# Revoke a card If your cardholder reports their card as lost or stolen, or if there's confirmed fraudulent activity, you can revoke the card to permanently freeze it and automatically decline any new transactions. You can also schedule cards to be revoked automatically after a specified lifetime or date. You do not need to suspend an active card before revoking it. > **Note** > > Revoking a card is a one-way action. The card cannot be reactivated. You can revoke a card using: - [The Dashboard](#Revoke_a_card_in_the_Dashboard) - [The API](#Revoke_a_card_using_the_API) - [Your app](#Revoke_a_card_in_your_app) - [Your website](#Revoke_a_card_on_your_website) --- ## Revoke a card in the Dashboard You must have on of the following [user roles](https://www.checkout.com/docs/business-operations/use-the-dashboard/manage-users/user-permissions.md): - Admin - A custom role with the `Manage Issuing data` permission 1. Sign in to the [Dashboard](https://dashboard.checkout.com). 2. Go to _Issuing_ > _Cards_. 3. Select the card you want to revoke. 4. In the _Card details_ page that appears, select _Revoke card_. --- ## Revoke a card using the API Call the [Revoke a card](https://api-reference.checkout.com/tag/Cards/#operation/revokeCard) endpoint, and provide the card ID prefixed with `crd_` as the `{cardId}` path parameter. In the request body, set the `reason` field to one of the following reasons for revoking the card: - `expired` - `reported_lost` - `reported_stolen` > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `POST` `https://{prefix}.api.checkout.com/issuing/cards/{cardId}/revoke` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/issuing/cards/{cardId}/revoke` ### Request example ```json { "reason": "reported_lost" } ``` ### Response example ```json { "_links": { "self": { "href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq242dcd6fdn5gifcq1491", "actions": [ "GET" ], "types": [ "application/json" ] }, "controls": { "href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq242dcd6fdn5gifcq1491", "actions": [ "GET" ], "types": [ "application/json" ] } } } ``` --- ## Schedule card revocation To help decrease the likelihood of fraud, you can schedule cards to be revoked automatically using: - [The Dashboard](#Schedule_card_revocation_in_the_Dashboard) - [The API ](#Schedule_card_revocation_using_the_API) You can also set a revocation date or a lifetime value when you first [issue a card using the API](https://www.checkout.com/docs/card-issuing/issue-a-card.md#Create_a_card_using_the_API). > **Note** > > If you schedule a revocation date after the end of the card's lifetime, the card is revoked when it expires. ### Schedule card revocation in the Dashboard You must have on of the following user roles: - Admin - A custom role with the `Manage Issuing data` permission 1. Sign in to the [Dashboard](https://dashboard.checkout.com). 2. Go to _Issuing_ > _Cards_, and select the card you want to auto-revoke. 3. On the _Card details_ page, select the _Revoke card_ dropdown, and then select _Schedule revoke date_. 4. Select the revocation date, and then select _Confirm_.
A revocation timer appears next to the card summary on the _Card details_ page. 5. To update or remove the revocation date, select the date in the revocation timer.
To update, select a new date.
To remove, select _Clear_. 6. Select _Confirm_. ### Schedule card revocation using the API Instead of revoking a card immediately, you can schedule it to be revoked at a future date. Checkout.com revokes the card at midnight (00:00) UTC on that date, without any further action from you or the cardholder. To schedule a card's revocation, set the `scheduled_revocation_date` field when you call one of the following endpoints: - [Create a card](https://api-reference.checkout.com/tag/Cards/#operation/createCard) - [Update card details](https://api-reference.checkout.com/tag/cards/PATCH/issuing/cards/%7BcardId%7D) – You can also use this endpoint to reschedule a card's existing revocation date. The `scheduled_revocation_date` value must be a future date in the ISO 8601 `YYYY-MM-DD` format. #### Revoke a scheduled card early You can revoke a card before its scheduled revocation date using any of the other methods on this page. We revoke the card immediately and clear its scheduled revocation date. #### Clear a scheduled revocation date To cancel a scheduled revocation, call the [Update card details](https://api-reference.checkout.com/tag/cards/PATCH/issuing/cards/%7BcardId%7D) endpoint and set `scheduled_revocation_date` to `null`. --- ## Revoke a card in your app After you've integrated the Card Management [Android SDK](https://www.checkout.com/docs/developer-resources/sdks/card-issuing-sdks/card-management-android-sdk.md) or [iOS SDK](https://www.checkout.com/docs/developer-resources/sdks/card-issuing-sdks/card-management-ios-sdk.md), you can revoke cards in your mobile app. Follow these steps: 1. Call the `getCards()` method to get a list of the cardholder's cards: **Android SDK** ```kotlin cardManager.getCards { result: Result> -> result.onSuccess { // You receive a list of the cardholder's cards that you can display in your UI // The card details returned include the last four digits of the PAN, expiry date, cardholder name, card status, and card ID }.onFailure { // If something goes wrong, you receive an error with more information } } ``` **iOS SDK** ```swift cardManager.getCards { result in switch result { case .success(let cards): // You receive a list of the cardholder's cards that you can display in your UI // The card details returned include last four digits of the PAN, expiry date, cardholder name, card status, and card ID case .failure(let error): // If something goes wrong, you receive an error with more information } } ``` 2. Call the `Card.possibleStateChanges()` method to request the possible statuses you can change the card to: **Android SDK** > **Note** > > From SDK version 3.0.0, all callback methods are deprecated. > Update your integration to use [suspending methods](https://www.checkout.com/docs/developer-resources/sdks/card-issuing-sdks/card-management-android-sdk.md#SDK_functions) instead. ```kotlin // Returns a list of possible statuses you can change the card to val possibleNewStates = card.possibleStateChanges // You can revoke the card if the status was returned by possibleStateChanges if (possibleNewStates.contains(CardState.REVOKED)) { // This is a destructive and irreversible action - once revoked, the card cannot be reactivated // We recommended that you request UI confirmation that your user intended to perform this action // You can choose to pass an optional reason for why you're revoking the card val reason: CardRevokeReason? = CardRevokeReason.STOLEN { val result = card.revoke(reason)) handleCardStateTransition(result) } // DEPRECATED using callbacks card.revoke(reason, completionHandler) } ``` **iOS SDK** > **Note** > > From SDK version 4.0.0, all callback methods are deprecated. > Update your integration to use [async methods](https://www.checkout.com/docs/developer-resources/sdks/card-issuing-sdks/card-management-ios-sdk.md#SDK_functions) instead. > All async methods throw a `CardManagementError` that you need to handle. ```swift import CheckoutCardManagement class YourObject { // Returns a list of possible statuses you can change the card to let possibleNewStates = card.possibleStateChanges // You can revoke the card if the status was returned by possibleStateChanges if possibleNewStates.contains(.revoked) { // This is a destructive and irreversible action - once revoked, the card cannot be reactivated // We recommended requesting user confirmation in the UI that they intend to perform this action // Optionally, you can pass the reason for revoking the card let reason: CardRevokeReason? = .lost do { try await cardManager.revoke(reason: reason) } catch let error as CardManagementError { // Revocation failed - Handle the error } // DEPRECATED using completions card.revoke(reason: reason, completionHandler: cardStateChangeCompletion) } ``` 3. Complete the change to `revoked` status: **Android SDK** ```kotlin fun cardStateChangeCompletionHandler(result: Result): Unit { result .onSuccess { // The card status is successfully updated and reflected by both the back end and the SDK }.onFailure { // If something goes wrong, you receive an error with more details } } ``` **iOS SDK** ```swift func cardStateChangeCompletion(_ result: CheckoutCardManager.OperationResult) { switch result { case .success: // The card status is successfully updated and reflected by both the back end and the SDK case .failure(let error): // If something goes wrong, you receive an error with more details } } ``` --- ## Revoke a card on your website After you've integrated the Card Management [Web SDK](https://www.checkout.com/docs/developer-resources/sdks/card-issuing-sdks/card-management-web-sdk.md), you can revoke cards on your website or web application. Revoking a card is a one-way action, so we recommend requesting confirmation in your user interface that the cardholder intended to perform it. Initialize the SDK with your public API key: ```javascript const sdk = new window.CheckoutCardManagement(); ``` Call the `revokeCard()` method with the card ID prefixed with `crd_`, and a cardholder access token. The `options` object is optional, but if you provide it, you must also provide a `reason`. The revoke reasons differ from the suspend reasons. > **Warning** > > The SDK has no method to reverse a revocation. If the method returns a `NETWORK_ERROR`, the revocation might still have been applied, so call `getCardDetails()` to confirm the card's status instead of retrying the call. ```javascript try { const result = await sdk.revokeCard('crd_fa6psq242dcd6fdn5gifcq1491', 'cardholderAccessToken', { // 'expired' | 'reported_lost' | 'reported_stolen' reason: 'reported_stolen', }); console.log(result.cardId); // 'crd_fa6psq242dcd6fdn5gifcq1491' console.log(result.status); // 'revoked' console.log(result.revokedAt); // ISO 8601 timestamp console.log(result.reason); // 'reported_stolen' } catch (error) { console.error(error.code, error.message); } ``` If the request fails, the SDK rejects with an error object containing a `code` and a `message`. For the full list of codes, see [Handle errors](https://www.checkout.com/docs/developer-resources/sdks/card-issuing-sdks/card-management-web-sdk.md#Handle_errors). --- ## Subscribe to webhooks You can set up webhooks to be notified when cards are revoked: 1. [Configure your webhook server](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/configure-your-webhook-server.md). 2. Subscribe to the [Card revoked](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/card_revoked.md) webhook.