Manage your Cards

Once a card is issued, you can perform several management actions using the Unified Card APIs. These actions allow you to control card usage, respond to potential fraud scenarios, and manage operational events such as lost or damaged cards.

Card Lifecycle

The CARD lifecycle defines a card's journey from initiation to activation to termination. Each status serves a critical role in maintaining the security of the funds and the usability of the card. By transitioning through these states, the system ensures that cards are only usable when in the hands of the verified owner and provides mechanisms to mitigate risk in case of loss or theft.

Issuance PENDING → SHIPPED The card is created and enters the inactive physical lifecycle.

Activation: SHIPPED → ACTIVE Proceeds through ACTIVATION_INITIATED to enable transactions.

Maintenance: ACTIVE ↔ FREEZED A temporary state managed via FREEZE_INITIATED and UNFREEZE_INITIATED.

Termination: ACTIVE → CANCELLED A permanent state. After CANCELLATION_INITIATED, the card is fully blocked.

Phase	Status	Description
Issuance & Activation	`PENDING`	Card is created in the system but remains inactive.
Issuance & Activation	`SHIPPED`	Physical card is in transit and cannot be used, preventing fraud if intercepted.
Issuance & Activation	`ACTIVATION_INITIATED`	Transition state triggered when the customer begins activation.
Issuance & Activation	`ACTIVE`	Card is fully functional for all transaction types (POS, ATM, Online).
Security & Temporary Suspension	`FREEZE_INITIATED` / `FREEZED`	Card is temporarily paused; all transactions are declined.
Security & Temporary Suspension	`UNFREEZE_INITIATED`	Request to restore the card to `ACTIVE` status without changing details.
Terminal States	`CANCELLATION_INITIATED`	System is processing a request to permanently shut down the card.
Terminal States	`CANCELLED` (Blocked)	Terminal state; card is permanently deactivated and cannot be reactivated.

The following actions are supported for both Debit and Prepaid cards.

Freeze a Card

Freezing a card temporarily blocks all transaction authorizations without permanently cancelling the card. This is useful when a card is misplaced, suspected of unauthorized activity, or needs to be temporarily restricted. Use the following endpoint to freeze a card POST /v1/customer/id/{customer_id}/issuance/card/id/{card_id}/freeze. When submitting this request, it is required to include:

reason – The reason for freezing the card
freezeTill – The date until which the card should remain frozen

While a card is frozen, all transaction attempts will be declined until the card is unfrozen.

Unfreeze a Card

Unfreezing a card restores the card to an ACTIVE state and allows transactions to resume. This action is typically used when a previously frozen card is confirmed to be safe for use. Use this endpoint to unfreeze a card POST /v1/customer/id/{customer_id}/issuance/card/id/{card_id}/unfreeze. After the request is processed, the card can be used again for transactions.

Terminate/ Cancel a Card

Cancelling a card permanently deactivates the card. This action cannot be reversed. Common scenarios include:

Card permanently compromised
Employee or user offboarding
Expired program or budget

Using this endpoint POST /v1/customer/id/{customer_id}/issuance/card/id/{card_id}/cancel you can cancel a card. For Prepaid cards, ensure that any remaining balance is unloaded before cancelling the card.

Replace a Card

Replacing a card blocks the existing card and issues a new card for the same cardholder. The replacement card is generated with a new CVV, and expiration date. This action is typically used when a card is Lost, Stolen or Damaged. Use this endpoint to replace a card POST /v1/customer/id/{customer_id}/issuance/card/id/{card_id}/replace.

After the request is completed, the replacement card is issued and shipped according to the configured Card Program settings. You will then be required to Enable the phyiscally delivered card to you via the POST request to this endpoint /v1/customer/id/{customer_id}/account/id/{account_id}/debitCard/id/{card_id}/enablePhysicalCard