# Activate a card You must activate the following cards before the cardholder can perform transactions: - Newly created physical cards - Virtual cards created using the API with `"activate_card": false` - Suspended cards You can activate cards using: - [The Dashboard](#Activate_a_card_in_the_Dashboard) - [The API](#Activate_a_card_using_the_API) - [Your app](#Activate_a_card_in_your_app) - [Your website](#Activate_a_card_on_your_website) You can also [schedule a card's activation](#Schedule_card_activation) for a future date or time, instead of activating it immediately. --- ## Let cardholders activate their own cards The cardholder can activate the card in the following ways: - Performing their first Chip and PIN transaction at a point of sale (PoS) – This also enables the card for contactless payments. - Withdrawing cash from an ATM To show the cardholder their card's personal identification number (PIN) in your mobile app, use the [Android](https://www.checkout.com/docs/developer-resources/sdks/card-issuing-sdks/card-management-android-sdk.md) or [iOS](https://www.checkout.com/docs/developer-resources/sdks/card-issuing-sdks/card-management-ios-sdk.md) Card Management SDK. You can also send them the PIN by mail. > **Note** > > Cardholders cannot make contactless payments until after they perform a Chip and PIN transaction, even if the card is already active. --- ## Activate a card in the Dashboard You must have one of the following [user roles](https://www.checkout.com/docs/business-operations/use-the-dashboard/manage-users/user-permissions.md): - Admin - Support manager - A custom role with the `Create and edit cards and cardholders; Simulate transactions` permission 1. Sign in to the [Dashboard](https://dashboard.checkout.com). 2. Go to _Issuing_ > _Cards_. 3. Select the card you want to activate. 4. On the _Card details_ page, select _Activate card_. --- ## Activate a card using the API Call the [Activate a card](https://api-reference.checkout.com/tag/Cards/#operation/activateCard) endpoint. Provide the card ID, prefixed with `crd_`, as the `{cardId}` path parameter. Alternatively, use the [Update card details](https://api-reference.checkout.com/tag/cards/PATCH/issuing/cards/%7BcardId%7D) endpoint to update the card status. > **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}/activate` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/issuing/cards/{cardId}/activate` ### Response example ```json { "last_activated_on": "2019-09-10T10:11:12Z", "_links": { "self": { "href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq242dcd6fdn5gifcq1491" }, "revoke": { "href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq242dcd6fdn5gifcq1491/revoke" }, "suspend": { "href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq242dcd6fdn5gifcq1491/suspend" }, "controls": { "href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq242dcd6fdn5gifcq1491", "actions": ["GET"], "types": ["application/json"] } } } ``` --- ## Activate a card in your app After you integrate 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 activate cards in your mobile app. > **Note** > > To activate cards in your app, you must migrate to Android SDK version 3.0.0 or iOS SDK version 4.0.0. For guidance on how to update your integration, see Support – [Issuing Card Management SDKs migration guide](https://support.checkout.com/hc/en-us/articles/32194131879698). ### Retrieve the cardholder's cards > **Note** > > The `getCards()` method throws a `CardManagementError` that you must catch. For example, use `catch`, as shown in the following example, or `runCatching`. Call the `getCards()` method to get all the cardholder's cards, or `getCard(cardId)` to get a specific card: **Android SDK** ```kotlin // Call coroutineBased getCards in the context of a coroutineScope try { // Get all the cardholder's cards cardManager.getCards(statuses = setOf(CardState.ACTIVE, CardState.REVOKED)) // Get a specific card cardManager.getCard(cardId: "") } catch (e: CardManagementError) { when (error) { is CardManagementError.Unauthenticated -> // Prompt login is CardManagementError.ConnectionIssue -> // Show network error else -> // Handle other errors } } ``` **iOS SDK** ```swift do { // Get all the cardholder's cards let cards = try await cardManager.getCards(statuses: [.active, .suspended]) // Get a specific card let cards = try await cardManager.getCard(withID: cardId, statuses: [.active,.suspended]) } catch let error as CardManagementError { switch error { case .authenticationFailure: // Handle the authentication error default: // Handle other errors } } ``` ### Check the possible status changes Read the `Card.possibleStateChanges` property to get the statuses you can change the card to: **Android SDK** ```kotlin // Returns a list of possible statuses you can change the card to val possibleNewStates = card.possibleStateChanges // You can activate the card if the status was returned by possibleStateChanges if (possibleNewStates.contains(CardState.ACTIVE)) { { val result = card.activate() handleCardStateTransition(result) } } ``` **iOS SDK** ```swift import CheckoutCardManagement class YourObject { // Returns a list of possible statuses you can change the card to let possibleNewStates = card.possibleStateChanges // You can activate the card if the status was returned by possibleStateChanges if possibleNewStates.contains(.active) { do { try await cardManager.activate() } catch let error as CardManagementError { // activation failed - handle error accordingly } } } ``` ### Change to active status Complete the change to `active` 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 } } ``` --- ## Activate a card on your website After you integrate the Card Management [Web SDK](https://www.checkout.com/docs/developer-resources/sdks/card-issuing-sdks/card-management-web-sdk.md), you can activate cards on your website or web app. Initialize the SDK with your public API key: ```javascript const sdk = new window.CheckoutCardManagement(); ``` Call the `activateCard()` method with the card ID, prefixed with `crd_`, and a cardholder access token. If the card is already active or revoked, the call fails with an `INVALID_CARD_STATE` error. > **Note** > > Make sure you pass a cardholder access token to `activateCard()`. The method does not accept the single-use payment token. ```javascript try { const result = await sdk.activateCard('crd_fa6psq242dcd6fdn5gifcq1491', 'cardholderAccessToken'); console.log(result.cardId); // 'crd_fa6psq242dcd6fdn5gifcq1491' console.log(result.status); // 'active' console.log(result.activatedAt); // ISO 8601 timestamp } catch (error) { console.error(error.code, error.message); } ``` If the request fails, you receive an error object that contains a `code` and a `message`. If you receive a `NETWORK_ERROR`, the card might already be active. 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). --- ## Schedule card activation Instead of activating a card immediately, you can schedule it to activate at a future date or time. Checkout.com activates the card at the scheduled time, without any further action from you or the cardholder. To schedule a card's activation, set the `scheduled_activation_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 activation date. The `scheduled_activation_date` value must be in the future, and use one of the following ISO 8601 formats: - Date only – `YYYY-MM-DD`. The card activates at midnight (00:00) UTC. - Date and time – `YYYY-MM-DDTHH:mmZ` for UTC, or `YYYY-MM-DDTHH:mm±HH:mm` with a UTC offset. If you include a time, it must be: - On the hour - At least one hour later than the time you send the request For example, if you send the request at `14:35`, you can set the activation time to `16:00`, `17:00`, and so on. > **Note** > > You cannot set `"activate_card": true` and provide `scheduled_activation_date` in the same Create a card request. If you do, the request returns an error. ### Activate a scheduled card early You can activate a card before its scheduled activation date using any of the other methods on this page. We activate the card immediately and clear its scheduled activation date. ### Clear a scheduled activation date To cancel a scheduled activation, call the [Update card details](https://api-reference.checkout.com/tag/cards/PATCH/issuing/cards/%7BcardId%7D) endpoint and set `scheduled_activation_date` to `null`. --- ## Subscribe to webhooks To receive webhooks when a physical or digital card's activation status changes: 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 following webhooks: - [Card activated](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/card_activated.md) - [Digital card activated](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/digital_card_activated.md) - [Digital card deactivated](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/digital_card_deactivated.md)