Card Lifecycle — Operator Workflow
This is a brief, end-to-end map for operators — the people who run the card program day to day. It answers two questions: how is a card generated, and how is it managed once it exists (assign, activate, and every status in between). It stitches together two deeper references:
- The Card Payment System design specs — the customer/admin-facing model (statuses, assignment, activation, CVM).
- Vận hành phía Issuer — what actually
runs inside xperise (service
card-core) to produce and personalize physical cards.
Follow the links for field-level detail; this page is the overview.
The lifecycle at a glance
A card passes through two phases: it is first generated & issued, then managed for the rest of its life. xperise runs a closed-loop program, so xperise is the issuer — it owns the card numbers, the keys, and the whole lifecycle.
Phase 1 — How a card is generated
A card exists as a virtual card, a physical card, or both at once. The two paths differ sharply in effort.
Virtual card — instant
Created in the app, no production. The corporate admin fills the issue-card form, and the card is provisioned immediately; its credentials are revealed only inside the employee's app (never emailed in clear). It is ready to be assigned/activated in the same sitting.
Physical card — a batch, produced on the issuer side
Physical cards are a longer, asynchronous flow: xperise mints the numbers, a perso bureau
(the card manufacturer) prints and chips the plastic, and only then can a card be issued and
activated. These steps run in card-core and are driven by the xperise system admin / platform,
not the corporate customer.
| # | Step | Endpoint (illustrative) | Result |
|---|---|---|---|
| 1 | Create print order | POST /admin/physical-cards/print-orders | Mints N PAN + pan_token; stock rows created ordered (chip UID still unknown) |
| 2 | Export file to bureau | GET …/print-orders/{id}/file | CSV (pan_token, PAN, last4, expiry) handed to the bureau; order → exported |
| 3 | Import chip UIDs back | POST /admin/physical-cards/uid-import | Bureau returns pan_token → chip_uid; stock ordered → available (damaged plastic → spoiled) |
| 4 | Allocate to a corporate | POST /admin/physical-cards/allocate | Stock available → allocated to a company's pool |
| 4b | Pre-personalize (optional) | POST …/perso/prepare + …/perso/confirm | Writes keys to the chip before hand-off; perso_state → PERSONALIZED |
ordered is not availableA freshly-ordered row means "the number exists, but the plastic does not yet." Nobody knows the chip's UID until the bureau reports it — which is why step 3 is a UID return, not a UID send. Only a card with a UID can be allocated.
For the full step-by-step (file format, key management, chip generations, error codes) see Sản xuất & phát hành thẻ vật lý.
Phase 2 — How a card is managed
Once a card record exists, everything a corporate admin does happens in the Corporate Portal: assign it, activate it, fund and control it, and eventually retire it. Card management never moves real money except by reclaiming a balance back to the company wallet.
Step A — Assign (to one employee, or to no-one)
Assignment is a binary choice:
- To one employee — the card is bound to that person, inherits the employee's cost center(s) and stays in sync, and enforces the per-employee hard cap. Never more than one employee.
- To no-one (a bearer card) — usable by whoever holds it and knows the verification secret; may optionally be linked to one cost center. Good for shared/pool/petty-cash cards.
Step B — Activate (the gate that makes a card spendable)
Activation confirms possession (this physical card) and identity (the rightful holder) before any money can move. Three variants:
| Variant | Path | When |
|---|---|---|
| Employee claim ✅ | Employee proves possession (tap / scan / code) + OTP, sets their own secret → ACTIVE | Default — best segregation of duties |
| Admin full-activation | Admin activates with a temporary secret, forced change on first use → ACTIVE | Low-limit cards, or when staff can't self-serve |
| Bearer activation | Admin sets the card secret → ACTIVE (no employee claim) | Unassigned / pool cards |
Full detail: Card activation.
Step C — In-life management
While a card is ACTIVE, operators can:
- Fund & control — allocate/top-up the card balance (top-up is always available), configure the monthly reset, and set limits, channels, and allowed vendors.
- Freeze / unfreeze — instantly block and unblock (
ACTIVE ⇄ FROZEN) for suspicion or leave. - Reassign / unassign — move to another employee or return to the pool; remaining balance is reclaimed to the company wallet by default.
- Replace / reissue — for a damaged, expiring, or compromised card; carries over holder + policy.
- Report lost/stolen — immediate, permanent kill of the token (
LOST). - Cancel / terminate — retire the card (
CANCELLED) and reclaim its balance; used for offboarding.
Card statuses (the state machine)
The design model tracks a card through these states. A card can move money only in ACTIVE, and
every transition is audit-logged with actor + reason.
| Status | Can spend? | Meaning |
|---|---|---|
ISSUED | No | Produced/created, in the company pool, unassigned |
ASSIGNED | No | Bound to an employee, awaiting activation |
ACTIVE | Yes | Spendable — assigned or bearer |
FROZEN | No | Temporarily blocked, reversible |
LOST | No | Reported lost/stolen — terminal, token killed |
CANCELLED | No | Terminated — terminal; balance reclaimed to wallet |
EXPIRED | No | Past expiry — terminal |
Operator caveats — the design model vs. what card-core runs today
The management model above is the design spec. The live card-core service implements a leaner
version, so know the mapping before you write UI or reports against it:
| Design spec | What card-core actually stores |
|---|---|
ISSUED / ASSIGNED | Pre-activation the card is stock (ordered → available → allocated), not yet a cards row |
ACTIVE | Card row inactive → active (cardholder OTP activation is the only "turn money on" gate) |
FROZEN / LOST / CANCELLED | Collapse to card status blocked |
EXPIRED | Card status expired |
| CVM = PIN or OTP | No PIN exists. CVM is verification_preference: qr_app (default), sms_otp, or static_code |
Batch QA / SHIPPED / DELIVERED | Not modeled — QA and shipping live outside card-core today |
Two more operator notes: spoiled plastic is never reissued (a printed number is retired, not recycled), and there is no dedicated reissue flow yet — replacing a lost/expired physical card means revoking the credential and re-running print-order → allocate → activate. See Những gì card-core chưa mô hình hoá.
Who does what
| Actor | Owns |
|---|---|
| xperise system admin / platform | Print orders, UID import, allocation, pre-personalization, key issuance (issuer side) |
| Perso bureau | Prints plastic, fits chips, returns chip UIDs |
| Perso station | Writes diversified keys onto the chip (PENDING → PERSONALIZED) |
| Corporate super admin / card manager | Issue, assign, activate, fund, freeze, replace, cancel |
| Finance / approver | Approves large orders and balance/limit increases (maker-checker) |
| Cardholder (employee) | Claims & activates their card, sets verification, self-freezes |
Related
- Card Payment — lifecycle, activation, CVM, acceptance modes.
- Card Management — Functional Spec — the full function-by-function reference.
- Issue Card — Flow & Logic — the issue-card form and branching.
- Corporate Portal — where management sits among the other modules.
- Sản xuất & phát hành thẻ vật lý (phía issuer) — the real
card-coregeneration flow. - Payment System Overview — the two-layer model behind card balance + company wallet.