> ## 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.

# Cards · Overview

> Issue virtual cards to companies or employees, query cards, open receiving accounts for dedicated-balance cards, retrieve secure card details, and run the full virtual-to-physical chain (production → shipping → activation → PIN).

## 📄 Guide

Issuing always starts virtual: the card is usable the moment the application passes; when a physical card is needed, upgrade the activated virtual card under the same number. This page walks "apply → query → display the PAN → upgrade to physical" with each endpoint's key parameters and prerequisites.

## Applying for a virtual card

`POST /open-api-corp/card/v1/apply` — acceptance returns an `cardApplyId`; risk checks and card creation run asynchronously, with the final state pushed as `CARD_CREATED` / `CARD_REJECTED` (fallback `GET /card/v1/query-apply`).

| Field                       | Required                   | Description                                                                                                                                                                                                                                                                                                                        |
| --------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cardApplyRef`              | Yes                        | ≤64; your unique application identifier (the idempotency key)                                                                                                                                                                                                                                                                      |
| `subjectType` + `subjectId` | Yes                        | `ORGANIZATION`→`organizationId` / `CUSTOMER`→`customerId`; the holder must be ACTIVE                                                                                                                                                                                                                                               |
| `cardProfileId`             | Yes                        | One of the four card types (must match the subjectType); see [Overview · Card types](../getting-started/overview)                                                                                                                                                                                                                  |
| `custodianCustomerId`       | Required for company cards | The custodian: the `customerId` of an ACTIVE employee of the same company                                                                                                                                                                                                                                                          |
| `ruleIds`                   | Required for SHARED cards  | ≤5 velocity rules bound at issue time; each must exist, belong to the same company and be ACTIVE, and amount-limit currencies must intersect the card's settlement currencies; **no duplicates in the array (not silently deduped)**; any failing entry rejects the whole request before acceptance — no `cardApplyId` is produced |

<Note>
  Common rejections: `CARD_RULE_REQUIRED` (a SHARED card without rules — an empty array counts as none), `CARD_RULE_DUPLICATE` (the same rule carried twice), `CARD_LIMIT_EXCEEDED` (over the card cap — live cards and in-flight applications counted together), `SUBJECT_INVALID` (custodian missing or not a valid employee of the company).
</Note>

Query the application: `GET /card/v1/query-apply?cardApplyId=...` — `status=SUCCEED` returns the `cardId`; on `REJECTED` the `errorCode` is fixed at `CARD_RISK_REJECTED` (internal risk codes are not passed through).

## Querying cards

* **Single card**: `GET /open-api-corp/card/v1/query?cardId=...` — returns `panFirst6` / `panLast4` (never the full PAN), the company, the holder, `cardProfileId`, `cardNetwork` (VISA / MASTERCARD / UPI), `cardCurrency` and status.
* **List**: `GET /open-api-corp/card/v1/list`, filterable by `organizationId` / `subjectType` / `subjectId` / `status`, paginated with `page` / `pageSize`.

## Opening a receiving account for a dedicated-balance card

`POST /open-api-corp/card/v1/open-va` — opens bank virtual accounts (VAs) per currency for a dedicated-balance card: send `cardId` + `fundingCurrencies` (USD / HKD, one or more); `data` comes back `null` — read the account numbers through [get deposit account information](./deposits). Cards funded by the company pool cannot open VAs (`CARD_NOT_DEDICATED`). A dedicated-balance card can also skip the VA and be funded from the company pool instead — see [Funding and reconciliation](./funding-and-reconciliation).

## Retrieving secure card details

`POST /open-api-corp/card/v1/retrieve-secure-card` — returns ciphertext-level `encryptedPan` / `encryptedCvv2` / `encryptedExpireDate` plus a per-call random `iv`, for decryption and display in your own frontend. **PCI DSS-allowlisted partners only** (`PCI_NOT_CERTIFIED` otherwise); partners without PCI DSS integrate the DCS hosted secure card page.

<Warning>
  **Decryption contract**: AES/GCM/NoPadding with a 128-bit tag, keyed with your SK; the three fields share one `iv`. **CVV2 and expiry are fetched live and must never be cached**; clear text must never be persisted in any form (databases, files, logs, caches, analytics or tracing), and the frontend masks by default (first 6, last 4).
</Warning>

## Virtual to physical

Four steps: **upgrade application → track shipping → activate → set the PIN**. The steps are detailed in [Physical cards](./physical-cards); card states are in [State machines and freezing](../basic-concepts/states-and-freezing).

**① Upgrade application**: `POST /open-api-corp/card/v1/virtual-to-physical` — send `cardApplyRef` (idempotency key), `organizationId`, `cardId` (must be an ACTIVE virtual card), `cardLayoutCode` (the card-face code, values issued by DCS per partner configuration), `embossingName` (≤26, first embossed line) and optional `embossingName2`. The shipping address is read from the holder / custodian and **locked as a snapshot** — a missing address returns `SHIPPING_ADDRESS_REQUIRED`; an in-flight upgrade on the same card returns `CARD_CONVERT_IN_PROGRESS`.

**② Track shipping**: `GET /open-api-corp/card/v1/shipping-info` — returns `trackingNumber` / `trackingCompanyName` (null before dispatch); dispatch pushes the webhook `CARD_SHIPPED`.

**③ Activate**: `POST /open-api-corp/card/v1/activate` — requires the card to have shipped (`CARD_NOT_SHIPPED` otherwise); the endpoint is idempotent; success pushes `CARD_ACTIVATED`.

**④ Set the PIN**: `POST /open-api-corp/card/v1/set-pin` — requires activation. The PIN and the identity-check fields (`encryptedPin` / `encryptedCvv2` / `encryptedExpireDate` / `encryptedPanLast4`) are AES-GCM encrypted with your SK, the four ciphertexts sharing one `iv` — the same crypto contract as retrieve-secure-card, in the opposite direction. The clear PIN must be 4 digits, no runs, no repeats (`PIN_RULE_VIOLATION`).

## Related webhooks

`CARD_CREATED` / `CARD_REJECTED` / the card status-change notification / `CARD_SHIPPED` / `CARD_ACTIVATED`.

## Next steps

* Build velocity rules before issuing SHARED cards: [Setting spend limits](./spend-limits)
* Fund a dedicated-balance card: [Funding and reconciliation](./funding-and-reconciliation)
* In this group: [Applying for a virtual card](./applying-virtual-cards) · [Secure card details](./secure-card-details) · [Physical cards](./physical-cards)