Managing Cards · Overview - DCS Technical Documentation

📄 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). 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.

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
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
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
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
Activate a physical card	End user	Guidance page with `action=ACTIVE_PHYSICAL_CARD`; the user activates the card once it arrives	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
Add to a digital wallet	End user	Call the wallet binding API to push the card into Apple Wallet or Google Wallet	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.

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)

{
  "externalUserId": "user_xxxxxxxx",
  "block": true,
  "cardId": "card_xxxxxxxx"
}

Unfreeze a card (verification code required)

{
  "externalUserId": "user_xxxxxxxx",
  "block": false,
  "cardId": "card_xxxxxxxx",
  "smsCode": "<sms-otp>"
}

Response example

{
  "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.

The block endpoint only moves a card between NORMAL ⇄ FROZEN (or ACTIVE ⇄ FROZEN).

Next steps

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 — 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 — 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) — 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.

​📄 Guide

​Virtual cards vs physical cards

​Two capability delivery paths (important)

​Mental model: the card state machine

​Operations at a glance

​Retrieving card details

​Freezing and unfreezing

​Next steps