Implementation Guide
Card Lifecycle
Understand the complete card status state machine — from issuance through blocking and replacement.
Every card in the M2P platform follows a defined lifecycle with clear status transitions. Understanding this lifecycle is essential for building user experiences around card management.
Card Status State Machine
Status Reference
| Status | Code | Can Transact | Description |
|---|---|---|---|
| Unallocated | UL | No | Card has been created in the system but not yet assigned to a customer |
| Active | AV | Yes | Card is active and can be used for all enabled transaction types |
| Locked | TL | No | Temporarily frozen by the customer — can be unlocked at any time |
| Blocked | BL | No | Permanently blocked (lost, stolen, or compromised) — cannot be reversed |
| Closed | CL | No | Card program has been closed and the card is decommissioned |
| Inactive | IA | No | Card has been issued but not yet activated by the customer |
Status Transitions
Allowed Transitions
| From | To | Trigger | API |
|---|---|---|---|
| Unallocated | Active | Customer registration / card issuance | POST /registration-manager/v3/register |
| Active | Locked | Customer requests temporary freeze | POST /card-manager/lockCard |
| Locked | Active | Customer unlocks card | POST /card-manager/unlockCard |
| Active | Blocked | Card reported lost/stolen/compromised | POST /card-manager/blockCard |
| Locked | Blocked | Card reported lost while locked | POST /card-manager/blockCard |
| Active / Blocked | Replaced | Replacement card requested | POST /card-manager/replaceCard |
Blocked Transitions
| Attempted | Reason |
|---|---|
| Blocked → Active | Blocking is permanent — use card replacement instead |
| Blocked → Locked | Cannot lock an already blocked card |
| Closed → Any | Closed cards cannot be reactivated |
Blocking is irreversible. Once a card is blocked, the customer must receive a replacement card. The replacement card gets a new kit number and card number, but the wallet balance is automatically transferred.
Card Replacement Flow
When a card is replaced, the platform automatically:
- Blocks the old card permanently
- Issues a new card with a new kit number and card number
- Transfers the full wallet balance to the new card
- Returns the new card details to your application