Skip to main content

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

​
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.
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).

​
Virtual to physical

Four steps: upgrade application → track shipping → activate → set the PIN. The steps are detailed in Physical cards; card states are in State machines 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). CARD_CREATED / CARD_REJECTED / the card status-change notification / CARD_SHIPPED / CARD_ACTIVATED.

​
Next steps