Viewing Encrypted Card Details - DCS Technical Documentation

📄 Guide

For security and compliance reasons (PCI DSS), a card’s full number (PAN), CVV and expiry date count as highly sensitive data and are never returned in plaintext by the ordinary card lookup endpoints. Those endpoints return masked data only, such as cardMantissa, the last four digits of the PAN; the full number is shown exclusively through the H5 hosted guidance page described on this page. As a licensed issuer with its own BINs, DCS presents the sensitive data securely inside its own hosted page, which is what allows partners without PCI certification to show card details to their end users compliantly. To let an end user see the full card details, you must use the secure flow on this page.

The one mechanism in the DeCard-Managed model: the H5 hosted guidance page

In the DeCard-Managed model, DCS does not offer an endpoint that returns encrypted card data to the partner’s backend for the partner to decrypt. The only supported mechanism for showing full card details is the DCS-hosted H5 guidance page: The partner calls the guidance page endpoint with action=CARD_INFO and DCS returns a single-use guidance link; the partner hands that link to the end user to open in their own browser, and the full PAN, CVV and expiry are rendered to the end user by the DCS-hosted page, so the plaintext never passes through the partner’s backend.

Card details rendered by the DCS-hosted H5 page

Because the plaintext is only ever rendered by the DCS-hosted page and never lands in the partner’s backend, partners without PCI certification can still let their end users see their card details safely.

Security notes

Never store a card’s full number, CVV or expiry date in the partner’s backend or on any persistent medium.
Only request the link when there is a real need, for example when the end user actively taps “show card number”.
The guidance link is a single-use, short-lived credential. Hand it to the end user promptly once you have it, and do not cache or forward it.

The three-step flow

The secure display flow in the DeCard-Managed model comes down to three steps: Step 1: call the guidance page endpoint for a link — the partner’s backend calls POST /redirect/v2/guidance-link with action=CARD_INFO and the card identifier, and DCS returns a single-use hosted guidance page link in data. Step 2: hand the link to the end user — the partner passes the link to the end user’s frontend. Do not open or cache the link in the partner’s backend. Step 3: the DCS-hosted page renders the card details — the end user opens the link in a browser and the DCS-hosted H5 page renders the full PAN, CVV and expiry; the plaintext never passes through the partner’s backend.

Endpoint (V2 recommended, card located by `cardId`)

POST /redirect/v2/guidance-link
Content-Type: application/json

For the authentication headers and signature, see Authentication Guide.

Request parameters (card details flow, `action=CARD_INFO`)

Field	Type	Required	Description
`action`	String	Yes	Always `CARD_INFO` for card details
`externalUserId`	String	Yes	User ID, max length 50
`successRedirectUrl`	String	Yes	Redirect URL used on success, max length 300
`errorRedirectUrl`	String	Yes	Redirect URL used on failure, max length 300
`cardId`	String	Yes	Card ID; V2 locates the specific card by `cardId`, and it is required in the `CARD_INFO` flow
`referer`	String	No	Referrer, used for security checks, max length 300
`userAgent`	String	No	User agent, used for security checks, max length 300
`language`	String	No	Language of the customer-facing `guidance-link`, max length 10, lowercase hyphenated and case-sensitive: `zh` / `en` / `ko` / `ja` / `zh-Hant` / `th` / `vi`
`theme`	String	No	Theme, max length 10, for example `blue` (recommended)
`mode`	String	No	Display mode, max length 10, for example `dark` / `light` (recommended)
`selectCardPageShow`	String	No	When the user holds only one card: `0` = still show the card selection page, `1` = skip it and go straight to the card details page, max length 1
`primaryColor`	String	No	Primary colour, max length 7, for example `#FFFFFF` (recommended)

The required fields are action / externalUserId / successRedirectUrl / errorRedirectUrl / cardId. theme and mode are optional, but sending them every time is recommended.

{
  "action": "CARD_INFO",
  "externalUserId": "<masked: user ID>",
  "cardId": "<masked: card ID>",
  "successRedirectUrl": "https://your-app.example.com/card/ok",
  "errorRedirectUrl": "https://your-app.example.com/card/err",
  "language": "zh",
  "theme": "blue",
  "mode": "light"
}

Response

Every response uses the common envelope { code, message, messageDetail, data } and there is no success boolean; the envelope is explained once in Authentication Guide. On success code = SYS_SUCCESS and data is a string: the guidance page link for the end user to open. messageDetail is a structured message object (its schema has seven sub-fields: message / title / type / icon / action / linkTitle / linkUrl) used to carry structured messaging; on an ordinary success every sub-field is an empty string, and the system fills them in as needed:

{
  "code": "SYS_SUCCESS",
  "message": "",
  "messageDetail": {
    "message": "",
    "title": "",
    "type": "",
    "icon": "",
    "action": "",
    "linkTitle": "",
    "linkUrl": ""
  },
  "data": "https://<dcs-hosted-guidance-page-url>"
}

Hand that link (the data field, a plain URL string) to the end user to open in their frontend, and the DCS-hosted page renders the full PAN, CVV and expiry.

messageDetail sub-fields

messageDetail is a structured message object with seven sub-fields, used to carry business messaging or error information. On an ordinary success every sub-field is an empty string, and the system fills them in as needed:

Sub-field	Type	Description
`type`	String	Message type: `INFO` / `WARN` / `ERROR`
`icon`	String	Icon identifier, which the frontend can map to an icon
`action`	String	Suggested action code, such as `RETRY` or `CONTACT_SUPPORT`
`message`	String	Body text of the message, written for the end user
`title`	String	Message title
`linkTitle`	String	Label of the actionable link
`linkUrl`	String	Target of the actionable link

Common error response

On failure, code carries the specific business error code for that failure (there is no generic failure code). Below is a typical error response for a frozen card (only NORMAL cards support the lookup). Note that even when the request fails (messageDetail.type=ERROR) the HTTP status is still 200, so decide success or failure from code rather than from the HTTP status:

{
  "code": "CARD_CARD_FROZEN_STATUS_UNSUPPORTED",
  "message": "card is frozen",
  "messageDetail": {
    "message": "The card is frozen, so its details cannot be viewed at the moment.",
    "title": "Lookup failed",
    "type": "ERROR",
    "icon": "error",
    "action": "RETRY",
    "linkTitle": "",
    "linkUrl": ""
  },
  "data": ""
}

Which messageDetail sub-fields are populated in which situation, and whether they appear together, is ultimately determined by what the API actually returns.

For the other action values on the guidance page (KYC guidance, ordering and activating a physical card, updating the PIN, Travel Rule, extra KYC documents and so on) and the fields each of them requires, see H5 KYC / Card Application Guidance Page.

Prerequisites

The card has been issued and you hold its cardId; see Issuing Cards.
You have confirmed which externalUserId the card belongs to.
You have confirmed the card’s status: only a card in NORMAL status can have its sensitive details queried and displayed. Querying a FROZEN card returns the error code CARD_CARD_FROZEN_STATUS_UNSUPPORTED, and any other non-NORMAL status likewise cannot be queried. In addition, a LUMINARY card whose annual fee has not been paid returns the error code CARD_ANNUAL_FEE_NOT_CHARGED. The full state machines (virtual cards: NORMAL / FROZEN / CANCELLED; physical cards have their own: UN_APPLY / INACTIVE / ACTIVE / REPLACE / FROZEN / CANCELLED) are described in Managing Cards · Overview.
When the details are shown through the hosted H5 page, DCS’s page performs these status checks itself — the partner does not need to run them.

Next steps

For freezing and unfreezing a card, card replacement and resetting the PIN, see Managing Cards · Overview.
For the common guidance page fields and the other action flows, see H5 KYC / Card Application Guidance Page.

On returning encrypted card data: the DeCard-Managed model offers no endpoint that returns encrypted card data to the partner’s backend for the partner to decrypt, and there is no client-side encryption or decryption flow. Sensitive card details are always shown through the H5 hosted guidance page described above.

​📄 Guide

​The one mechanism in the DeCard-Managed model: the H5 hosted guidance page

​The three-step flow

​Endpoint (V2 recommended, card located by cardId)

​Request parameters (card details flow, action=CARD_INFO)

​Response

​messageDetail sub-fields

​Common error response

​Prerequisites

​Next steps