> ## 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. # Retrieving secure card details > The two paths: PCI and SecureToken ## 📄 Guide Whether or not you hold PCI certification, you can let end users securely view the full card number, CVV and expiry date of their own card. DCS offers a separate path for each of these two partner types: an encrypted payload returned to your backend, or a DCS-hosted guidance page. As a licensed issuer with its own BINs, DCS encrypts secure card details end to end in transit, and sensitive data is never persisted in the clear. Secure card details (full PAN, CVV2, expiry date) are highly sensitive data governed by PCI DSS. The card management endpoints only return the first 6 and last 4 digits of the card number (`panFirst6` / `panLast4`); to obtain the full value in the clear, you must use one of the secure retrieval paths described on this page. **Security notes** * Never store decrypted secure card details in your backend or on any persistent medium. * Only issue a retrieval request when it is genuinely needed, for example when the user actively taps "View card number". * Always use an up-to-date crypto library, and keep the key (`enterpriseSecret`) safe. See [Authentication and security](../../integration-resources/authentication). ### Two paths: start by checking whether you hold PCI certification DCS splits partners into two groups based on PCI certification, and the two paths are entirely different: Two paths for retrieving secure card details Two paths for retrieving secure card details | Path | Who it is for | Who decrypts / displays the plaintext | Does the partner backend touch the plaintext? | | ----------------------------- | -------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------- | | Path 1 `retrieve-secure-card` | Partners **holding PCI certification** | Partner backend decrypts, partner frontend displays | Yes (the encrypted payload is returned and decrypted by the partner) | | Path 2 `guidance-link` | Partners **without PCI certification** | The DCS-hosted page shows the details directly to the end user | No (plaintext never passes through the partner backend) | > Which path you use is not a design choice; it is determined by your **PCI certification** status. Do not attempt to call Path 1 if you are not certified. *** ### Path 1: retrieve secure card details (PCI certified) > Who does it: the **partner** (backend call, decryption and frontend display). Available only to PCI-certified partners. #### Endpoint ```http theme={null} POST /open-api/card/v1/retrieve-secure-card Content-Type: application/json ``` For authentication headers and signing, see [Authentication and security](../../integration-resources/authentication). #### Request parameters | Field | Type | Required | Description | | -------- | ------ | -------- | -------------------------- | | `cardId` | String | Yes | Card ID, maximum length 50 | ```json theme={null} { "cardId": "card_xxxxxxxxxxxx" } ``` #### Response Every response uses the standard envelope `{ code, message, messageDetail, data }` (the envelope fields are explained once in [Authentication and security](../../integration-resources/authentication)). All sensitive fields inside `data` are **encrypted**: ```json theme={null} { "code": "...", "message": "...", "messageDetail": { }, "data": { "cardId": "card_xxxxxxxxxxxx", "pan": "", "cvv2": "", "expireDate": "", "iv": "" } } ``` | Field | Type | Description | | ------------ | ------ | --------------------------------------------------------------------------------------------- | | `cardId` | String | Card ID | | `pan` | String | Full card number (**encrypted**) | | `cvv2` | String | CVV2 (**encrypted**) | | `expireDate` | String | Expiry date (**encrypted**); once decrypted, the format is `mm/yy` | | `iv` | String | Initialization vector (IV) used for this encryption; use it to decrypt the three fields above | #### Decryption The `pan`, `cvv2` and `expireDate` fields are encrypted with **AES-GCM**. The key is the `enterpriseSecret` assigned to you during onboarding (Base64-decoded into key bytes, with the key length determined by the number of decoded bytes), and the initialization vector is the `iv` returned alongside the payload. The official Java implementation from the source documentation (`AES/GCM/NoPadding`, 12-byte IV, 128-bit authentication tag) is: ```java theme={null} // Excerpt from the AESUtil sample in the official card management documentation public static String decryptGCM(String base64Ciphertext, String enterpriseSecret, String base64IV) { SecretKey key = new SecretKeySpec(Base64.getDecoder().decode(enterpriseSecret), "AES"); byte[] iv = Base64.getDecoder().decode(base64IV); byte[] ciphertext = Base64.getDecoder().decode(base64Ciphertext); Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", "SunJCE"); GCMParameterSpec spec = new GCMParameterSpec(128, iv); // 128-bit authentication tag cipher.init(Cipher.DECRYPT_MODE, key, spec); return new String(cipher.doFinal(ciphertext), StandardCharsets.UTF_8); } ``` All three fields share the same `iv`. Once decrypted, render them in your frontend and **do not write them back or persist them**. > Encryption specification: the key is the Base64-decoded byte string of `enterpriseSecret` (its bit length follows the secret length; production currently uses 16 bytes, i.e. AES-128). A random 12-byte IV is generated per request and returned in the `iv` field. The 128-bit GCM tag is appended to the ciphertext, and `ciphertext + authTag` is Base64-encoded as a whole. The caller must also be on the PCI whitelist, the `cardId` must belong to the calling Enterprise, and the card status must be `ACTIVATED`. *** ### Path 2: view the details on the hosted guidance page (no PCI certification) > Who does it: the **partner** requests the link, and **DCS** hosts the page and shows the plaintext to the end user. Without PCI certification, DCS provides a hosted H5 page that displays the secure card details, so plaintext **never passes through the partner backend**. All you need to do is obtain a one-time guidance page link and have the end user open it in your frontend. #### Endpoint ```http theme={null} POST /open-api/card-redirect/v1/guidance-link Content-Type: application/json ``` #### Request parameters (card details scenario, `type=1`) | Field | Type | Required | Description | | ----------------------- | ------ | ---------------------- | ----------------------------------------------------------------------------------------------------------- | | `type` | String | Yes | Always pass `1` (card details lookup) | | `cardId` | String | Required when `type=1` | Card ID, maximum length 50 | | `customerId` | String | Yes | Customer ID, maximum length 50 | | `language` | String | Yes | Language, `zh` / `en` (non-Chinese-speaking countries map to en) | | `theme` | String | Yes | Theme, maximum length 10, for example `default` / `blue` (`blue` is supported for card details lookup only) | | `mode` | String | Yes | `light` / `dark` | | `userAgent` | String | Yes | Maximum length 300 | | `successfulRedirectUrl` | String | No | Redirect URL on success, maximum length 200 | | `errorRedirectUrl` | String | No | Redirect URL on failure, maximum length 200 | | `submitAutoClosed` | String | No | Whether to close the page automatically after a successful submission: `Y` / `N` | | `primaryColor` | String | No | Primary color, maximum length 7, for example `#FFFFFF` | > `otpStatus` is required only for `type=2` (set PIN) and `type=3` (reset PIN); it is not needed for a card details lookup (`type=1`). The other `type` values (face verification, KYC and so on) and their required fields are documented in [Hosted guidance page](../kyc/h5-kyc-guidance). ```json theme={null} { "type": "1", "cardId": "card_xxxxxxxxxxxx", "customerId": "cust_xxxxxxxxxxxx", "language": "zh", "theme": "default", "mode": "light", "userAgent": "Mozilla/5.0 ...", "submitAutoClosed": "Y" } ``` #### Response `data` is a single string: the guidance page link for the end user to open. ```json theme={null} { "code": "...", "message": "...", "messageDetail": { }, "data": "https://" } ``` Hand that link to the end user to open in your frontend. The DCS-hosted page then shows the full card number, CVV and expiry date directly, without any of it passing through the partner backend. > The guidance page link is backed by a temporary token held in Redis: the token is deleted as soon as it has been validated, so it is a single-use credential and is also subject to a TTL. Pass it to the end user immediately after you obtain it, and do not cache or reuse it. The server verifies that the card belongs to the given user and Enterprise. The public, unauthenticated validation endpoints are `/card-bridge/redirect/public/v1/secret-validate` and `/card-bridge/redirect/public/v1/check-token-valid`. *** ### Prerequisites * A card has been issued successfully and you have its `cardId` (see [Card issuance](./card-issuing)). * Path 1: DCS has confirmed that you hold PCI certification, and you are storing `enterpriseSecret` securely. * Path 2: you have confirmed that the `cardId` belongs to the `customerId` you are passing. ## Next steps Once you can retrieve secure card details, move on to the freeze / unfreeze, reset PIN and cancellation operations in [Card management](./card-management). For encryption, decryption and key handling details, see [Authentication and security](../../integration-resources/authentication).