> ## Documentation Index > Fetch the complete documentation index at: https://docs.thedecard.com/llms.txt > Use this file to discover all available pages before exploring further. # Managing Cards ยท Overview > The landing page for the card management group: the two card forms (virtual and physical), the card state machine, and how capabilities such as freezing, unfreezing and reading card details are delivered along two different paths (REST endpoints and hosted guidance pages). ## ๐Ÿ“„ Guide Once a user has passed KYC, you can issue them a card and manage it for the rest of its life: freeze it to stop fraudulent use, cancel it when it is lost, activate it once the physical card arrives, reset the PIN when the cardholder forgets it. As a licensed issuer with its own BINs, DCS keeps card state in sync with the card scheme and the issuer processor underneath, so you only deal with the business semantics: what state is this card in, and which operations does that state allow. **Every card belongs to a user**, so make sure the user exists and has passed KYC before you issue a card (see [Managing Users](../managing-users/overview)). This group covers card issuing, viewing sensitive card details, freezing and unfreezing, managing the PIN, ordering and activating a physical card, and adding a card to Apple Wallet or Google Wallet (Push Provisioning). ### Virtual cards vs physical cards Cards come in two forms, and they differ in how they are delivered and managed: * **Virtual card**: usable the moment it is issued, with no shipping and no activation step. * **Physical card**: shipped to the cardholder and **must be activated on arrival** before it can be used; activation and shipping lookups are covered below. ### Two capability delivery paths (important) In the DeCard-Managed model, card management is **not** exposed as a symmetrical set of standalone REST endpoints. It is delivered along two paths, so do not assume the "one endpoint per action" model you may know from other platforms: | Capability | Delivered via | Entry point | | :----------------------------------------------- | :----------------------- | :----------------------------------------------------------- | | Freeze / unfreeze | **REST endpoint** | `POST /card/v2/block` | | Read card details and status | **REST endpoint** | `GET /card/v2/detail` | | View sensitive card details (PAN / CVV / expiry) | **Hosted guidance page** | `/redirect/v2/guidance-link` โŸถ `action=CARD_INFO` | | Order a physical card | **Hosted guidance page** | `/redirect/v2/guidance-link` โŸถ `action=CREATE_PHYSICAL_CARD` | | Activate a physical card | **Hosted guidance page** | `/redirect/v2/guidance-link` โŸถ `action=ACTIVE_PHYSICAL_CARD` | | Update the PIN | **Hosted guidance page** | `/redirect/v2/guidance-link` โŸถ `action=UPDATE_PIN` | > Sensitive operations โ€” reading sensitive card details, ordering and activating a physical card, updating the PIN โ€” all run through the hosted guidance page `/redirect/v2/guidance-link`, selected by the `action` enum. The user completes the operation inside a DCS-hosted page with SMS verification, and sensitive data never touches the partner's backend. The published `action` values for guidance-link are `KYC_GUIDE` / `CARD_INFO` / `CREATE_PHYSICAL_CARD` / `ACTIVE_PHYSICAL_CARD` / `UPDATE_PIN` / `TRAVEL_RULE` / `KYC_EXTRA_DOC`. The DeCard-Managed model has no standalone reset-pin, activate, convert-to-phy or invalidate REST endpoints. ## Mental model: the card state machine DCS expresses a card's lifecycle stage through its status fields, and every management operation is ultimately a way of driving that state machine. Virtual and physical cards each have their own set of status values. Card state machine Card state machine **Virtual card status (`cardStatus`)** | Status | Meaning | | :------------ | :--------------------------------------------------- | | **NORMAL** | The card is active and can be used normally | | **FROZEN** | The card is frozen and temporarily unusable | | **CANCELLED** | The card has been canceled and can no longer be used | **Physical card status (`physicalCardStatus`)** | Status | Meaning | | :------------ | :----------------------------------------------------------------------- | | **UN\_APPLY** | No physical card has been ordered yet | | **INACTIVE** | A physical card has been ordered but not activated, so it cannot be used | | **ACTIVE** | The card is active and can be used normally | | **REPLACE** | The card is going through card replacement | | **FROZEN** | The card is frozen and temporarily unusable | | **CANCELLED** | The card has been canceled and can no longer be used | > **How cardholders reach card replacement**: the published API surface has no card replacement `action` or REST endpoint; `REPLACE` appears only as one of the `physicalCardStatus` values. Contact the DCS team to confirm the entry point for card replacement. ## Operations at a glance Each operation is summarised in one line below, with its entry point. The REST operations (freeze/unfreeze, read card details) are documented further down this page; the guidance-page operations (sensitive card details, physical card order and activation, PIN) each have their own page. | Operation | Who performs it | Summary | Details | | :--------------------------- | :-------------- | :------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------- | | Read card details and status | Partner | Use `/card/v2/detail` to read card status and balances; leave `cardId` empty to list every card the user holds | [This page โ€บ Retrieving card details](#retrieving-card-details) | | Freeze / unfreeze | Partner | Use `/card/v2/block` and flip the `block` boolean to freeze against fraud or restore the card | [This page โ€บ Freezing and unfreezing](#freezing-and-unfreezing) | | View sensitive card details | End user | Guidance page with `action=CARD_INFO` shows the full PAN, CVV and expiry inside a DCS-hosted page | [Viewing Encrypted Card Details](./viewing-encrypted-card-details) | | Order a physical card | End user | Guidance page with `action=CREATE_PHYSICAL_CARD`; the user fills in the shipping details and submits the order | [Issuing Cards](./issuing-cards) | | Activate a physical card | End user | Guidance page with `action=ACTIVE_PHYSICAL_CARD`; the user activates the card once it arrives | [Issuing Cards](./issuing-cards) | | Reset or update the PIN | End user | Guidance page with `action=UPDATE_PIN`; the user sets the PIN inside the hosted page and the plaintext never reaches the partner | [Managing a Card's PIN](./managing-a-cards-pin) | | Add to a digital wallet | End user | Call the wallet binding API to push the card into Apple Wallet or Google Wallet | [Push Provisioning](./push-provisioning) | ### Retrieving card details Read card details with `GET /card/v2/detail`. On this endpoint `cardId` is optional: **pass a value** to query one specific card, **leave it empty** to list the cards the user holds. The `data` field is always an array. The response carries the card status (`cardStatus` for the virtual card and `physicalCardStatus` for the physical card, with the values shown in the state machine above) together with the balances tied to the card (`walletBalance` / `caBalance` / `cardBalance` / `balanceCurrency` / `billingCurrency`). Each card is tied to a user-level balance and authorization decisions are made inside DCS: that is the defining trait of the DeCard-Managed (dedicated-account) model. For balance management, see [User Balance](../managing-transactions/user-balance). > This endpoint identifies a card precisely with `cardId`. ### Freezing and unfreezing Freeze or unfreeze a card with `POST /card/v2/block`. It is a single endpoint, and the `block` boolean sets the direction: `block=true` freezes, `block=false` unfreezes. Freezing takes effect immediately, which is what you want when a card looks compromised or the user asks to pause it. | Field | Type | Required | Description | | :---------------------- | :------ | :----------------------- | :------------------------------------------------------ | | `externalUserId` | string | Yes | User ID | | `cardId` | string | Yes | Card ID | | `block` | boolean | Yes | `true` = freeze; `false` = unfreeze | | `smsCode` / `emailCode` | string | Required when unfreezing | Verification code for unfreezing; supply one of the two | * **Freezing** (`block=true`) normally needs no verification code. * **Unfreezing** (`block=false`) requires a verification code: supply **either** `smsCode` (SMS) **or** `emailCode` (email). **Freeze a card (no verification code)** ```json theme={null} { "externalUserId": "user_xxxxxxxx", "block": true, "cardId": "card_xxxxxxxx" } ``` **Unfreeze a card (verification code required)** ```json theme={null} { "externalUserId": "user_xxxxxxxx", "block": false, "cardId": "card_xxxxxxxx", "smsCode": "" } ``` **Response example** ```json theme={null} { "code": "SYS_SUCCESS", "message": "", "messageDetail": null, "data": true } ``` `data` is a boolean indicating **whether this freeze or unfreeze operation succeeded**: `true` = success, `false` = failure. The envelope `{code, message, messageDetail, data}` is the same across the API, as described in [Quickstart](../../getting-started/quickstart). > The `block` endpoint only moves a card between `NORMAL` โ‡„ `FROZEN` (or `ACTIVE` โ‡„ `FROZEN`). ## Next steps * [Issuing Cards](./issuing-cards) โ€” apply for a virtual or physical card for a user who has passed KYC. A virtual card is usable as soon as it is issued; a physical card is shipped and then activated. * [Viewing Encrypted Card Details](./viewing-encrypted-card-details) โ€” show the full PAN, CVV and expiry securely through a hosted guidance page (action=CARD\_INFO), without the data passing through the partner's backend. * [Managing a Card's PIN](./managing-a-cards-pin) โ€” let the user set or update the PIN inside a DCS-hosted page through a hosted guidance page (action=UPDATE\_PIN); the partner never handles the PIN, in plaintext or encrypted form. * [Push Provisioning (Apple / Google Pay)](./push-provisioning) โ€” add a DCS-issued Visa card to Apple Wallet or Google Wallet from inside your app, with no manual card entry in the wallet app.