Retrieving secure card details

📄 Guide

A card’s full number (PAN), CVV2 and expiry date are sensitive authentication data; the ordinary card queries return only panFirst6 / panLast4 (see the single-card query in Applying for a virtual card). To show the full card details to a cardholder, PCI DSS-certified partners call this page’s retrieve-secure-card for the ciphertexts and decrypt them for display themselves; partners without PCI DSS can integrate the DCS hosted secure card page instead. This page also covers open-va, the receiving-account endpoint for dedicated-balance cards.

POST /open-api-corp/card/v1/retrieve-secure-card

Returns ciphertext-level PAN / CVV2 / expiry for secure display in your frontend.

Only PCI DSS-certified partners may call this endpoint (PCI_NOT_CERTIFIED otherwise); partners without PCI DSS can integrate the platform’s hosted secure card page.

Request parameters

Field	Type	Required	Description
`companyId`	String	Yes	≤50; the requesting company ID
`cardId`	String	Yes	≤50; the card ID; must belong to your partnership and be ACTIVE

Response data

Field	Type	Description
`cardId`	String	The card ID
`encryptedPan`	String	The PAN (AES-GCM ciphertext)
`encryptedCvv2`	String	The CVV2 (ciphertext)
`encryptedExpireDate`	String	The expiry (ciphertext; plaintext format mm/yy)
`iv`	String	The random IV for this call (Base64), needed to decrypt

Decryption contract

Algorithm: AES/GCM/NoPadding with a 128-bit authentication tag.
Key: your SK.
IV: the three ciphertext fields encryptedPan / encryptedCvv2 / encryptedExpireDate share the same iv (randomly generated per call, returned Base64-encoded).

CVV2 and expiry are fetched live and must never be cached — call this endpoint again for fresh ciphertexts every time they need to be displayed.

Request and response examples

{
  "companyId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "cardId": "5185740066240790530"
}

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "cardId": "5185740066240790530",
    "encryptedPan": "UGFuTW9ja0NpcGhlclRleHRCYXNlNjQrVGFnMTZC",
    "encryptedCvv2": "Q3Z2Mk1vY2tDaXBoZXJUZXh0K1RhZzE2Qg==",
    "encryptedExpireDate": "RXhwTW9ja0NpcGhlclRleHQrVGFnMTZC",
    "iv": "MTIzNDU2Nzg5MGFi"
  }
}

Error codes

Error code	Description
`PCI_NOT_CERTIFIED`	Secure card data access not enabled (not on the PCI allowlist)
`CARD_INVALID`	The card does not exist / does not belong to your partnership
`CARD_STATE_INVALID`	The card state does not allow viewing sensitive details; only ACTIVE / FROZEN

PCI DSS · Cardholder data protection

Under PCI DSS, the full PAN, CVV2 and expiry date are sensitive authentication data and must be handled end-to-end under the minimum-exposure principle:

Mask by default: the frontend shows only the masked PAN by default — first 6 and last 4 digits preserved (e.g. 531993 •••• •••• 8888); CVV2 and expiry are not shown by default.
Temporary display only when needed: decrypt and display the plaintext only when there is a genuine business need and the cardholder’s identity has been verified.
Plaintext never persisted: during display the plaintext must not be stored in any form — databases, files, logs, caches, analytics and tracing must all keep none of it; CVV2 must not be retained after authorization either.
Keys in a KMS: decryption keys must be held in a key management service (KMS) and rotated regularly.

Opening a receiving account for a dedicated-balance card

POST /open-api-corp/card/v1/open-va

Opens a top-up account (VA) per currency for a dedicated-balance card; you can then fund the card either by bank transfer or by allocation from the company pool (for funding and reconciliation see Funding and reconciliation).

Request parameters

Field	Type	Required	Description
`cardId`	String	Yes	≤50; the card ID; must belong to your partnership and be a dedicated-balance card
`fundingCurrencies`	`Array<String>`	Yes	The currencies to open VAs for (at least one; values `USD` / `HKD`; one VA per currency); no empty elements, no duplicate currencies — empty/duplicate/non-enum values → `DAPI_PARAM_INVALID`; the set must also be a subset of the company’s permitted currencies, and anything out of range rejects the whole request (no partial opening) → `CURRENCY_NOT_ALLOWED`

Response

An action endpoint: data is null. To read the account numbers that were opened, call get deposit account information with subjectType=CARD — opening a VA and reading its account number are two separate endpoints, and this one only opens.

Request and response examples

{
  "cardId": "5185740066240790531",
  "fundingCurrencies": ["USD", "HKD"]
}

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": null
}

Error codes

Error code	Description
`CARD_INVALID`	The card does not exist / does not belong to your partnership
`CARD_NOT_DEDICATED`	Not a dedicated-balance card; VAs cannot be opened
`CURRENCY_NOT_ALLOWED`	A requested currency is not in the company’s permitted list (the message names the currency)
`SUBJECT_INVALID`	The card’s ledger holder (account_holder) is missing, or the cardholder’s KYB/KYC name is missing (both holder-side problems that prevent opening a VA)

Next steps

Fund a dedicated-balance card by transfer or company-pool allocation, and reconcile: Funding and reconciliation
Upgrade an activated virtual card to a physical card under the same number: Physical cards

Getting Started

Basic Concepts

How to Use

Customer Success

Retrieving secure card details

📄 Guide