Activate, suspend, or revoke a card

Last updated: April 24, 2024

You can manage the status of a card by activating, suspending, or revoking it at any point.

The card’s status determines whether any restrictions are placed on it:

inactive: awaiting activation, unusable until activated
active: no restrictions applied
suspended: incoming authorizations will be declined
revoked: all transactions will be declined

By default:

new physical cards are marked as inactive
new virtual cards are marked as active

The following cards must be activated before the cardholder can perform transactions:

newly created physical cards
virtual cards created using the API with "activate_card": false in the request
suspended cards

You can activate a card using the:

Dashboard
API
SDK, if you've integrated the Issuing Android SDK or iOS SDK into your app

The cardholder can also activate the card themselves by performing their first Chip and PIN transaction at a point of sale (POS), or by withdrawing cash at an ATM.

To activate an inactive or suspended card in the Dashboard:

Go to the Card Issuing > Cards screen.
Select the card you want to activate.
In the Card details screen that appears, select Activate card.

You can activate a card with the API.

post

https://api.checkout.com/issuing/cards/{cardId}/activate


1{
2  "_links": {
3    "self": {
4      "href": "https://api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491"
5    },
6    "revoke": {
7      "href": "https://api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/revoke"
8    },
9    "suspend": {
10      "href": "https://api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/suspend"
11    }
12  }
13}

If you suspect your cardholder's card has been lost or stolen, or if there's suspected fraudulent activity, you can suspend a 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
recurring payments through merchant initiated transactions (MITs)
refunds
reversals
chargebacks

You can suspend a card using the:

Dashboard
API
SDK, if you've integrated the Issuing Android SDK or iOS SDK into your app

To suspend an active or inactive card in the Dashboard:

Go to the Card Issuing > Cards screen.
Select the card you want to suspend.
In the Card details screen that appears, select Suspend card.

You can suspend a card with the API.

post

https://api.checkout.com/issuing/cards/{cardId}/suspend

You can supply one of the following values in the request's optional reason field to state why you've suspended the card:

suspected_lost
suspected_stolen


1{
2  "reason": "suspected_lost"
3}


1{
2  "_links": {
3    "self": {
4      "href": "https://api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491"
5    },
6    "activate": {
7      "href": "https://api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/activate"
8    },
9    "revoke": {
10      "href": "https://api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/revoke"
11    }
12  }
13}

At this point, you can either reactivate the suspended card, or permanently revoke it.

If your cardholder reports their card as lost or stolen, or if there's confirmed fraudulent activity, you can revoke a card to permanently freeze it and automatically decline any new transactions.

You do not need to suspend a 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
API
SDK, if you've integrated the Issuing Android SDK or iOS SDK into your app

To revoke an active, inactive, or suspended card in the Dashboard:

Go to the Card Issuing > Cards screen.
Select the card you want to revoke.
In the Card details screen that appears, select Revoke card.

You can also schedule a date for a card to be automatically revoked:

Go to the Card Issuing > Cards screen.
Select the card you want to revoke.
Select the dropdown icon to view additional options.
Select Schedule revoke date.
Set a date for the card to be revoked.

To update or remove a card's revocation date, select the card in the Dashboard and click on the date displayed in the revocation message.

You can revoke a card with the API.

post

https://api.checkout.com/issuing/cards/{cardId}/revoke

You can supply one of the following values in the request's optional reason field to state why you've revoked the card:

expired
reported_lost
reported_stolen


1{
2  "reason": "reported_lost"
3}


1{
2  "_links": {
3    "self": {
4      "href": "https://api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
5      "actions": [
6        "GET"
7      ],
8      "types": [
9        "application/json"
10      ]
11    },
12    "controls": {
13      "href": "https://api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
14      "actions": [
15        "GET"
16      ],
17      "types": [
18        "application/json"
19      ]
20    }
21  }
22}

To help decrease the likelihood of fraud, you can set cards to be revoked automatically.

You can choose to set the card to auto-revoke using one of the following options:

setting the card's lifetime value during card creation
setting revocation_date in the card creation request
scheduling card revocation after the card is created

You can revoke a card a period of time after it was issued, using the lifetime.unit ("Months" or "Years") and lifetime.value fields. These fields must be set during card creation.

Cards are automatically revoked at the end of their specified lifetime.

For example, you can create a card with a lifetime of 3 months. On the last day of third month, the card is automatically revoked.

post

https://api.checkout.com/issuing/cards


1{
2  "type": "physical",
3  "cardholder_id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
4  "lifetime": {
5    "unit": "Months",
6    "value": 3
7  },
8  "reference": "X-123456-N11",
9  "metadata": {
10    "udf1": "metadata1",
11    "udf2": "metadata2",
12    "udf3": "metadata3",
13    "udf4": "metadata4",
14    "udf5": "metadata5"
15  },
16  "card_product_id": "pro_7syjig3jq3mezlc3vjrdpfitl4",
17  "display_name": "HANNAH BRET",
18  "shipping_instructions": {
19    "shipping_recipient": "Hannah Bret",
20    "shipping_address": {
21      "address_line1": "123 High St.",
22      "address_line2": "Flat 456",
23      "city": "London",
24      "state": "London",
25      "zip": "W1T 4TJ",
26      "country": "GB"
27    },
28    "additional_comment": "string"
29  },
30  "activate_card": false
31}

For the full API specification, see the API reference.

You can set a specific date on which the card will be automatically revoked during card creation. If this date is past the card's lifetime, the card will be revoked at the end of the specified lifetime.

For example, you can set a card to be revoked on 2024-03-12 during card creation. If the date is within the card's lifetime, the card will be revoked on 2024-03-12.

post

https://api.checkout.com/issuing/cards


1{
2  "type": "physical",
3  "cardholder_id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
4  "lifetime": {
5    "unit": "Months",
6    "value": 6
7  },
8  "reference": "X-123456-N11",
9  "metadata": {
10    "udf1": "metadata1",
11    "udf2": "metadata2",
12    "udf3": "metadata3",
13    "udf4": "metadata4",
14    "udf5": "metadata5"
15  },
16  "revocation_date": "2024-03-12",
17  "card_product_id": "pro_7syjig3jq3mezlc3vjrdpfitl4",
18  "display_name": "HANNAH BRET",
19  "shipping_instructions": {
20    "shipping_recipient": "Hannah Bret",
21    "shipping_address": {
22      "address_line1": "123 High St.",
23      "address_line2": "Flat 456",
24      "city": "London",
25      "state": "London",
26      "zip": "W1T 4TJ",
27      "country": "GB"
28    },
29    "additional_comment": "string"
30  },
31  "activate_card": false
32}

For the full API specification, see the API reference.

Alternatively, after the card is created, you can set the card to be revoked on a specific date using the Schedule card revocation API.

For example, after the card is created, you can set it to be revoked on 2024-03-12.

post

https://api.checkout.com/issuing/cards/{cardId}/schedule-revocation


1{
2  "revocation_date": "2024-03-12"
3}

Before the revocation date, you can choose to update the scheduled revocation date.

However, if the revocation date is past the lifetime of a card, the card will be revoked at the end of its lifetime.

For example, consider the revocation date of a card is set to 2024-03-12. Any time before this date, you can update the revocation date to 2027-03-12.

post

https://api.checkout.com/issuing/cards/{cardId}/schedule-revocation


1{
2  "revocation_date": "2027-03-12"
3}

You can activate, suspend, or revoke your cardholder's cards from within your app, if you've integrated the Issuing Android SDK or iOS SDK.


1import androidx.compose.ui.text.TextStyle
2import com.checkout.cardmanagement.CheckoutCardManager
3import com.checkout.cardmanagement.model.Environment
4
5class YourObject {
6
7  // Sets the customizable UI properties for the secure components delivered
8  private val cardManagerDesignSystem = CardManagementDesignSystem(
9    textStyle = TextStyle(),
10    panTextSeparator = "-"
11  )
12
13  // Instantiates the core card manager object, which provides access to the SDK functionality
14  private val cardManager = CheckoutCardManager(
15    context = context,
16    designSystem = cardManagerDesignSystem,
17    environment = Environment.SANDBOX
18  )
19
20  // Authenticates the user with the access token retrieved from your back end
21  val token = "<ACCESS_TOKEN>"
22  cardManager.logInSession("<ACCESS_TOKEN>")
23
24  // Retrieves a list of the cardholder's cards
25  cardManager.getCards { result: Result<List<Card>> ->
26    result.onSuccess {
27      // You'll receive a list of cards that you can integrate inside your UI
28      // Returned card info includes last 4 digits (PAN), expiry date, cardholder name, card state, and card ID
29    }.onFailure {
30      // If something goes wrong, you'll receive an error with more details
31    }
32  }
33
34  // This will return a list of possible states that you can transition the card to
35  val possibleNewStates = card.possibleStateChanges
36
37  // You can activate the card, if the state was returned by possibleStateChanges
38  if (possibleNewStates.contains(CardState.ACTIVE)) {
39    card.activate(completionHandler)
40  }
41
42  // You can suspend the card, if the state was returned by possibleStateChanges
43  if (possibleNewStates.contains(CardState.SUSPENDED)) {
44    // You can choose to pass an optional reason for why you're suspending the card
45    val reason: CardSuspendReason? = CardSuspendReason.LOST
46    card.suspend(reason, completionHandler)
47  }
48
49  // You can revoke the card, if the state was returned by possibleStateChanges
50  // This is a destructive and irreversible action - once revoked, the card cannot be reactivated
51  // We recommended that you request UI confirmation that your user intended to perform this action
52  if (possibleNewStates.contains(CardState.REVOKED)) {
53    // You can choose to pass an optional reason for why you're revoking the card
54    val reason: CardRevokeReason? = CardSuspendReason.STOLEN
55    card.revoke(reason, completionHandler)
56  }
57
58  fun cardStateChangeCompletionHandler(result: Result<Unit>): Unit {
59    result
60      .onSuccess {
61        // Card state has been updated successfully, and will be reflected by both the back end and the SDK
62      }.onFailure {
63        // If something goes wrong, you'll receive an error with more details
64      }
65  }
66}


1import CheckoutCardManagement
2
3class YourObject {
4
5  // Sets the customizable UI properties for the secure components delivered
6  let cardManagerDesignSystem = CardManagementDesignSystem(font: .systemFont(ofSize: 22),
7                                                          textColor: .blue)
8
9  // Instantiates the core card manager object, which provides access to the SDK functionality
10  let cardManager = CheckoutCardManager(designSystem: cardManagerDesignSystem,
11                                       environment: .sandbox)
12
13  // Authenticates the user with the access token retrieved from your back end
14  let token = "<ACCESS_TOKEN>"
15  cardManager.logIn(with: token)
16
17  // Retrieves a list of the cardholder's cards
18  cardManager.getCards { result in
19    switch result {
20      case .success(let cards):
21      // You'll receive a list of cards that you can integrate inside your UI
22      // Returned card info includes last 4 digits (PAN), expiry date, cardholder name, card state, and card ID
23      case .failure(let error):
24      // If something goes wrong, you'll receive an error with more details
25    }
26  }
27
28  // This will return a list of possible states that you can transition the card to
29  let possibleNewStates = card.possibleStateChanges
30
31  // You can activate the card, if the state was returned by possibleStateChanges
32  if possibleNewStates.contains(.active) {
33    card.activate(completionHandler: cardStateChangeCompletion)
34  }
35
36  // You can suspend the card, if the state was returned by possibleStateChanges
37  if possibleNewStates.contains(.suspended) {
38    // You can choose to pass an optional reason for why you're suspending the card
39    let reason: CardSuspendReason? = .lost
40    card.suspend(reason: reason, completionHandler: cardStateChangeCompletion)
41  }
42
43  // We can revoke the card, if the state was returned by possibleStateChanges
44  // This is a destructive and irreversible action - once revoked, the card cannot be reactivated
45  // We recommended that you request UI confirmation that your user intended to perform this action
46  if possibleNewStates.contains(.revoked) {
47    // You can choose to pass an optional reason for why you're revoking the card
48    let reason: CardRevokeReason? = .lost
49    card.revoke(reason: reason, completionHandler: cardStateChangeCompletion)
50  }
51
52  func cardStateChangeCompletion(_ result: CheckoutCardManager.OperationResult) {
53    switch result {
54    case .success:
55      // Card state has been updated successfully, and will be reflected by both the back end and the SDK
56    case .failure(let error):
57      // If something goes wrong, you'll receive an error with more details
58    }
59  }
60}

Activate, suspend, or revoke a card

Activate a card

Activate a card using the Dashboard

Activate a card using the API

Response example

Suspend a card

Suspend a card using the Dashboard

Suspend a card using the API

Request example

Response example

Revoke a card

Note

Revoke a card using the Dashboard

Revoke a card using the API

Request example

Response example

Automatically revoke a card

Set lifetime value

Set revocation date

Update revocation date

Manage a card's status with the Issuing SDKs