> ## 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.
# Virtual card
> Redundant screenshots removed
## Virtual card
Whichever market you serve and whatever kind of end user you serve, you can issue a virtual card that is ready to spend within seconds, with no card production or shipping to wait for. As a licensed issuer and its own BIN sponsor, DCS gives partners a compliant, controllable way to issue cards under the Partner-Managed model: the partner owns the spending limits, the partner makes the authorization decisions, and DCS handles card issuance, the card lifecycle and settlement with the card scheme.
A virtual card is a digital payment card with no physical medium. It carries the same spending authorization and status management capabilities as a physical card, and suits online payments, subscriptions, cross-border settlement and similar scenarios, which makes it the primary way funds flow between a partner and its end users.
***
## Why choose a virtual card
| Capability | Description |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Instantly usable** | No production or shipping step: the card is created as soon as the application succeeds and is **active by default**, so it can be authorized for spending right away. |
| **Secure details delivered encrypted** | The card number, CVV and expiry date can only be obtained through the encrypted endpoint and are rendered directly to the end user in your frontend, never landing in the partner backend, which lowers the risk of exposure. |
| **Full lifecycle control** | Freeze, unfreeze, cancel and replace are all supported. Using `cardId`, a partner can adjust a card's permissions in real time to handle loss reports, account anomalies and similar cases. |
| **Upgradable to a physical card** | A virtual card can later be converted to a physical card, keeping the same card number (see below). |
***
## Mental model: how a virtual card comes into being
Virtual card issuance is driven by a **card order**, and the whole process runs **asynchronously**: you submit one application request, DCS returns a `cardOrderId`, and you then track the status through the query endpoint or a webhook until it reaches a final state.
| Role | Responsibility |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Partner** | Collects user data, submits the application, tracks status, retrieves secure card details, and presents and manages the card for the end user |
| **DCS** | Creates the customer profile, runs KYC, issues the card with the card scheme channel, sends status callbacks, and manages settlement with the card scheme |
> The prerequisites for applying (the Enterprise record and the card profile), the full set of request fields and the card order state machine are all consolidated on the [Card issuance](./card-issuing) page and are not repeated here.
***
## Applying for a virtual card (at a glance)
**`POST /open-api/card-order/v1/apply-virtual`**
Minimum required fields:
| Field | Type | Required | Description |
| --------------- | ------ | -------- | ------------------------------------------------------------- |
| `profileId` | string | Yes | Card profile ID, provided by the DCS team (maximum length 50) |
| `cardOrderRef` | string | Yes | Idempotency key for the card order (maximum length 50) |
| `cardApplyMode` | string | Yes | Always `NORMAL` |
| `kycTicketId` | string | Yes | KYC ticket ID (returned by "apply for KYC") |
| `customerId` | string | Yes | User ID (returned by "create user") |
Before calling this endpoint, complete [Apply for KYC](../kyc/apply-kyc) to obtain a `kycTicketId`, then issue the card with `kycTicketId` + `customerId`.
A successful response returns the key details of the card order:
```json theme={null}
{
"code": "SYS_SUCCESS",
"message": "success",
"data": {
"cardOrderId": "CO_xxxxxxxx",
"profileId": "PF_xxxx",
"type": "VIRTUAL",
"customerId": "CU_xxxx",
"cardId": "CARD_xxxx",
"status": "PENDING",
"needExtraInfo": false,
"createTime": "2025-01-01T12:00:00+08:00",
"modifyTime": "2025-01-01T12:00:00+08:00"
}
}
```
**About the standard response envelope**: every endpoint wraps its result in `{ code, message, messageDetail, data }`. `code` is the system-level return code (such as `SYS_SUCCESS`), `message` is a short description, `messageDetail` is structured copy you can show directly to the end user (with `title`, `type`, `action`, `linkUrl` and similar), and the business payload sits inside `data`.
> The authentication headers and `Content-Type` required on the application request, as well as the dictionary of `code` values, are documented once in [Authentication and security](../../integration-resources/authentication).
For the full field reference, the encryption details, and how to handle `needExtraInfo` (supplementary KYC information), see [Card issuing flow](./card-issuing).
***
## Card order statuses (virtual card)
| Status | Meaning | Final state |
| ----------------------- | ------------------------------------------------------- | ----------- |
| `PENDING` | Initial status | No |
| `CUSTOMER_PASS` | Customer profile created successfully inside the system | No |
| `KYC_PASS` | KYC identity verification passed | No |
| `CHANNEL_CUSTOMER_PASS` | Customer created successfully on the channel side | No |
| `COMPLETED` | Virtual card created and activated successfully | Yes |
| `FAILED` | Final state after any step fails | Yes |
When the status is `FAILED`, both the response and the `CARD_ORDER` webhook carry `errorCode` and `errorReason`. For how the error codes are grouped, and whether a case can be retried, resolved by the user or fixed by resubmitting documents, see [Card application error codes](./card-order-codes).
> To track status, either call **`GET /open-api/card-order/v1/detail`** or subscribe to the `CARD_ORDER` webhook and receive updates passively.
***
## Converting a virtual card to a physical card
A virtual card can later be converted to a physical card. **What to expect**:
* The conversion produces a new `cardId`, different from the original virtual card's, but **both cards share the same card number**.
* Until the physical card is activated, all authorizations remain against the original virtual card.
* Once the physical card is activated, the original virtual card is canceled and authorizations move to the physical card.
For the exact steps, see [Physical card](./physical-card).
***
## Retrieving secure card details
The card number, CVV and expiry date of a virtual card are sensitive data, so they must be **retrieved** through the encrypted endpoint and rendered directly to the end user in your frontend:
* **Partners holding PCI certification** call `retrieve-secure-card` for the encrypted card details and decrypt them before showing the user.
* **Partners without PCI certification** present the details through the DCS hosted guidance page, so sensitive data never passes through the partner's systems.
See [Secure card details](./secure-card) for the full flow.
***
## Next steps
* With the prerequisites in place, go to [Card issuance](./card-issuing) for the complete field reference and the application modes.
* Once a card has been issued, see [Card management](./card-management) for freeze, unfreeze, cancellation and replacement.
* To cap per-transaction or periodic spending, see [Velocity limits](./velocity-limits).