Activate, suspend, or revoke a card
Beta
Last updated: March 13, 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 cards are marked as inactive.
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 three dot icon to view additional options.
- Select Schedule revocation.
- 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}6}7}
To help decrease the likelihood of fraud, you can set a card to revoke automatically after specified criteria are met. For example, you can set the card to auto-revoke:
- on a specific date, using the
revocation_date
field - a period of time after the card was issued, using the
lifetime.unit
("Months" or "Years") andlifetime.value
fields
You can also schedule a card to auto-revoke when you create the card.
post
https://api.checkout.com/issuing/cards/{cardId}/schedule-revocation
1{2"type": "physical",3"cardholder_id": "crh_d3ozhf43pcq2xbldn2g45qnb44",4"lifetime": {5"unit": "Months",6"value": 67},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": "2027-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": false32}
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.TextStyle2import com.checkout.cardmanagement.CheckoutCardManager3import com.checkout.cardmanagement.model.Environment45class YourObject {67// Sets the customizable UI properties for the secure components delivered8private val cardManagerDesignSystem = CardManagementDesignSystem(9textStyle = TextStyle(),10panTextSeparator = "-"11)1213// Instantiates the core card manager object, which provides access to the SDK functionality14private val cardManager = CheckoutCardManager(15context = context,16designSystem = cardManagerDesignSystem,17environment = Environment.SANDBOX18)1920// Authenticates the user with the access token retrieved from your back end21val token = "<ACCESS_TOKEN>"22cardManager.logInSession("<ACCESS_TOKEN>")2324// Retrieves a list of the cardholder's cards25cardManager.getCards { result: Result<List<Card>> ->26result.onSuccess {27// You'll receive a list of cards that you can integrate inside your UI28// Returned card info includes last 4 digits (PAN), expiry date, cardholder name, card state, and card ID29}.onFailure {30// If something goes wrong, you'll receive an error with more details31}32}3334// This will return a list of possible states that you can transition the card to35val possibleNewStates = card.possibleStateChanges3637// You can activate the card, if the state was returned by possibleStateChanges38if (possibleNewStates.contains(CardState.ACTIVE)) {39card.activate(completionHandler)40}4142// You can suspend the card, if the state was returned by possibleStateChanges43if (possibleNewStates.contains(CardState.SUSPENDED)) {44// You can choose to pass an optional reason for why you're suspending the card45val reason: CardSuspendReason? = CardSuspendReason.LOST46card.suspend(reason, completionHandler)47}4849// You can revoke the card, if the state was returned by possibleStateChanges50// This is a destructive and irreversible action - once revoked, the card cannot be reactivated51// We recommended that you request UI confirmation that your user intended to perform this action52if (possibleNewStates.contains(CardState.REVOKED)) {53// You can choose to pass an optional reason for why you're revoking the card54val reason: CardRevokeReason? = CardSuspendReason.STOLEN55card.revoke(reason, completionHandler)56}5758fun cardStateChangeCompletionHandler(result: Result<Unit>): Unit {59result60.onSuccess {61// Card state has been updated successfully, and will be reflected by both the back end and the SDK62}.onFailure {63// If something goes wrong, you'll receive an error with more details64}65}66}