Retrieving secure card details - DCS Technical Documentation

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

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

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

POST /open-api/card/v1/retrieve-secure-card
Content-Type: application/json

For authentication headers and signing, see Authentication and security.

Request parameters

Field	Type	Required	Description
`cardId`	String	Yes	Card ID, maximum length 50

{
  "cardId": "card_xxxxxxxxxxxx"
}

Response

Every response uses the standard envelope { code, message, messageDetail, data } (the envelope fields are explained once in Authentication and security). All sensitive fields inside data are encrypted:

{
  "code": "...",
  "message": "...",
  "messageDetail": { },
  "data": {
    "cardId": "card_xxxxxxxxxxxx",
    "pan": "<ciphertext: full card number>",
    "cvv2": "<ciphertext: CVV2>",
    "expireDate": "<ciphertext: expiry date, mm/yy once decrypted>",
    "iv": "<IV used for this encryption, Base64>"
  }
}

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:

// 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

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.

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

{
  "code": "...",
  "message": "...",
  "messageDetail": { },
  "data": "https://<DCS-hosted guidance page URL>"
}

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).
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. For encryption, decryption and key handling details, see Authentication and security.

​📄 Guide

​Two paths: start by checking whether you hold PCI certification

​Path 1: retrieve secure card details (PCI certified)

​Endpoint

​Request parameters

​Response

​Decryption

​Path 2: view the details on the hosted guidance page (no PCI certification)

​Endpoint

​Request parameters (card details scenario, type=1)

​Response

​Prerequisites

​Next steps

📄 Guide

Two paths: start by checking whether you hold PCI certification

Path 1: retrieve secure card details (PCI certified)

Endpoint

Request parameters

Response

Decryption

Path 2: view the details on the hosted guidance page (no PCI certification)

Endpoint

Request parameters (card details scenario, `type=1`)

Response

Prerequisites

Next steps