# Suspend a card If you suspect your cardholder's card has been lost, stolen, or used for fraudulent activity, you can suspend the card to temporarily freeze it and automatically block any new transactions. The following actions are still allowed on a suspended card: - Authorization requests linked to a previous transaction, for example, an incremental authorization - Chargebacks - Recurring payments through merchant-initiated transactions (MITs) - Refunds - Reversals - Tokenization You can suspend a card using: - [The Dashboard](#Suspend_a_card_in_the_Dashboard) - [The API](#Suspend_a_card_using_the_API) - [Your app](#Suspend_a_card_in_your_app) - [Your website](#Suspend_a_card_on_your_website) --- ## Suspend 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 suspend. 4. In the _Card details_ page that appears, select _Suspend card_. --- ## Suspend a card using the API Call the [Suspend a card](https://api-reference.checkout.com/tag/Cards/#operation/suspendCard) 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 suspending the card: - `suspected_lost` - `suspected_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}/suspend` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/issuing/cards/{cardId}/suspend` ### Request example ```json { "reason": "suspected_lost" } ``` ### Response example ```json { "_links": { "self": { "href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq242dcd6fdn5gifcq1491" }, "activate": { "href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq242dcd6fdn5gifcq1491/activate" }, "revoke": { "href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq242dcd6fdn5gifcq1491/revoke" } } } ``` You can now either [reactivate](https://www.checkout.com/docs/card-issuing/activate-a-card.md) the suspended card, or permanently [revoke](https://www.checkout.com/docs/card-issuing/manage-cards/revoke-a-card.md) it. --- ## Suspend 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 suspend 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 suspend the card if the status was returned by possibleStateChanges if (possibleNewStates.contains(CardState.SUSPENDED)) { // You can choose to pass an optional reason for why you're suspending the card val reason: CardSuspendReason? = CardSuspendReason.LOST { val result = card.suspend(CardSuspendReason.LOST)) handleCardStateTransition(result) } // DEPRECATED using callbacks card.suspend(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 suspend the card if the status was returned by possibleStateChanges if possibleNewStates.contains(.suspended) { // Optionally, you can pass the reason for suspending the card let reason: CardSuspendReason? = .lost do { try await cardManager.suspend(reason: reason) } catch let error as CardManagementError { // Suspension failed - Handle the error } // DEPRECATED using completions card.suspend(reason: reason, completionHandler: cardStateChangeCompletion) } ``` 3. Complete the change to `suspended` 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 } } ``` --- ## Suspend 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 suspend cards on your website or web application. Initialize the SDK with your public API key: ```javascript const sdk = new window.CheckoutCardManagement(); ``` Call the `suspendCard()` 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`. You can reactivate a suspended card later with `activateCard()`. ```javascript try { const result = await sdk.suspendCard('crd_fa6psq242dcd6fdn5gifcq1491', 'cardholderAccessToken', { // 'suspected_lost' | 'suspected_stolen' reason: 'suspected_lost', }); console.log(result.cardId); // 'crd_fa6psq242dcd6fdn5gifcq1491' console.log(result.status); // 'suspended' console.log(result.suspendedAt); // ISO 8601 timestamp console.log(result.reason); // 'suspected_lost' } 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`. If you receive a `NETWORK_ERROR`, the suspension might still have been applied, so call `getCardDetails()` to confirm the card's status before you retry. 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 suspended: 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 suspended](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/card_suspended.md) webhook.