Suspend an active card
Learn how to temporarily suspend an active card to prevent any new card transactions. This guide explains how to place a temporary hold on a card, which can be reactivated by the user later.
The user in this document pertains to both the individual and business user types.
Use Cases
- You want to temporarily lock a specific user card for security and control in cases where fraud is suspected.
- You want to lock a card temporarily due to contractual reasons.
- You want to set the card status from the
activeto alockedstate. - You want to add a feature to your application that allows users to self-suspend their cards.
Prerequisites
- The user profile risk assessment status must not be
risk_flagged. - The user profile must be in an
activestatus. - The user must have an
approvedKYC or KYB status. - The user account or wallet must be in an
activestatus. - The user card must be in an
activestatus.
API Workflow
1
[v1] Suspend an active card
Call the Suspend Card (DELETE /users/wallets/cards/{{card_id}}) without passing any type parameter, as an empty type parameter, which will default to a card suspension or locking.
Suspend Card request
curl --location --request DELETE 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/180ac588b91dc6bff6a5d42a671d1d6a' \
--header 'X-Auth-User-Id: {{user_id}}' \
--header 'Authorization: ••••••' \
--header 'Content-Type: application/x-www-form-urlencoded'Suspend Card response
{
"id": "180ac588b91dc6bff6a5d42a671d1d6a",
"number": "5545XXXXXXXX0000",
"status": "locked"
}2
[v2] Suspend an active card
The V2 Card Status API is currently only restricted to JIT-configured programs.
Call the Card Status (Lock) (PUT /users/wallets/cards/{{card_id}}/status) to lock or temporarily suspend a card by passing the action, origin , and reason for locking.
Card Status API (Lock) request parameters:
origin | action | reason | Description |
|
| blank or empty (not required) | The User wants to temporarily suspend their card |
|
|
| The User spots an unrecognised transaction |
|
|
| The User locks as a precautionary measure |
|
|
| The User has temporarily misplaced their card |
|
|
| The Partner risk / fraud engine flags a high-risk transaction or suspicious activity |
|
|
| The Partner detects suspicious transaction pattern |
|
|
| The Partner identifies elevated risk activity |
|
|
| The Partner locks for internal compliance or security concerns |
Card Status (Lock) request
curl --location --request PUT 'https://{{cards_base_url}}/{{program_code}}/v2/users/wallets/cards/{{card_id}}/statuses' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"action": "LOCK",
"origin": "USER",
"reason": "SUSPICIOUS_TRANSACTION"
}
'Card Status (Lock) response
{
"id": "{{card_id}}",
"status": "LOCKED",
"reason": "SUSPICIOUS_TRANSACTION",
"origin": "USER",
"updated_at": "2026-03-17 02:08:10.420987372 +0000 UTC"
}3
Update the card status display to reflect card suspension
It is recommended that you update the card status of the suspended card in your frontend and handle the scenarios for a suspended card:
- Display the status change to your user either as a badge or by graying out the card.
- Handle restrictions on displaying full card number and security code (CVC/CVV) details.
- Provide an option to do a self-service unsuspension of their locked card.
Related Links
On this page
- Suspend an active card