Physical cards - DCS Technical Documentation

📄 Guide

A physical card comes from an activated (ACTIVE) virtual card upgraded in place through “virtual to physical”. The PAN, expiry, CVV2 and cardId all stay the same throughout the upgrade — queries return the original virtual card’s details before activation and take effect as the physical card after it — so you never need to replace the card or migrate any targets after upgrading. For the card-state background see State machines and freezing. The four-step chain:

The shipping address hangs off the employee’s record; it is read when the virtual-to-physical application is accepted and locked as a snapshot — later address changes do not affect cards already in production.

① Upgrade application: virtual to physical

POST /open-api-corp/card/v1/virtual-to-physical

Upgrades an ACTIVE virtual card to a physical card under the same number. How the card ships depends on whether shippingAddressId is sent. Without it the card ships individually to the card’s holder / custodian, with the address and mailing phone number taken from that employee. With it the card ships in bulk to the address that id points to, and cards accepted on the same day under the same id go out together as one batch.

Request parameters

Field	Type	Required	Description
`companyId`	String	Yes	≤50; the requesting company ID
`cardPhysicalApplyRef`	String	Yes	≤64; your unique application identifier (the idempotency key); character set `^[A-Za-z0-9_-]+$`
`cardId`	String	Yes	≤50; the virtual card being upgraded; must belong to your partnership / company, currently be a virtual card and be ACTIVE; the holder / custodian is derived from this card
`cardLayoutCode`	String	Yes	The card-face code; must be a configured face (values are issued by DCS per partner configuration — not a fixed enum)
`embossingName`	String	Yes	≤20; the first embossed line on the card face
`embossingName2`	String	No	≤20; the second embossed line (optional)
`shippingAddressId`	String	No	≤50; the bulk shipping address id; without it the card ships to its holder / custodian

Response data

Field	Type	Description
`cardPhysicalApplyId`	String	The upgrade acceptance id

Request and response examples

// Scenario 1: individual shipping — no shippingAddressId, ships to the card's holder / custodian
{
  "companyId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "cardPhysicalApplyRef": "ext-v2p-0001",
  "cardId": "5185740066240790530",
  "cardLayoutCode": "LAYOUT_CLASSIC_BLACK",
  "embossingName": "DOE JOHN",
  "embossingName2": "EXAMPLE HK LIMITED"
}

// Scenario 2: bulk shipping — with shippingAddressId, ships to the address that id points to
{
  "companyId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "cardPhysicalApplyRef": "ext-v2p-0002",
  "cardId": "5185740066240790531",
  "cardLayoutCode": "LAYOUT_CLASSIC_BLACK",
  "embossingName": "LEE SIU MING",
  "embossingName2": "EXAMPLE HK LIMITED",
  "shippingAddressId": "100023"
}

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

Error codes

Error code	Description
`CARD_INVALID`	The card does not exist / does not belong to your partnership / is not ACTIVE
`CARD_NOT_VIRTUAL`	The card is already physical and cannot be converted again
`CARD_CONVERT_IN_PROGRESS`	The same card already has an in-flight (unfinished) upgrade application
`APPLY_DUPLICATE`	The same `cardPhysicalApplyRef` has already been accepted (idempotency)
`SHIPPING_ADDRESS_REQUIRED`	Individual shipping only: the holder / custodian has no shipping address on file
`SHIPPING_ADDRESS_INVALID`	Bulk shipping only: `shippingAddressId` is invalid, or that address may not be used for this card
`COUNTRY_SANCTIONED`	The destination country is on a sanctions list
`LIMIT_PHYSICAL_EXCEEDED`	Over the physical-card cap (company-level or holder-level)

Related webhooks: CARD_SHIPPED (dispatched) / CARD_ACTIVATED (activated).

② Tracking production and shipping

GET /open-api-corp/card/v1/shipping-info

Queries the physical card’s production and shipping progress plus the tracking number.

Request parameters

Field	Type	Required	Description
`companyId`	String	Yes	≤50; the requesting company ID
`cardId`	String	Yes	≤50; the card id

Response data

Field	Type	Description
`cardId`	String	The card id
`trackingNumber`	String	The tracking number (empty before dispatch)
`trackingCompanyName`	String	The carrier

Response examples (shipped / not shipped)

// Scenario 1: shipped
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "cardId": "5185740066240790530",
    "trackingNumber": "SF1234567890123",
    "trackingCompanyName": "SF Express"
  }
}

// Scenario 2: not yet shipped
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "cardId": "5185740066240790530",
    "trackingNumber": null,
    "trackingCompanyName": null
  }
}

Error code: CARD_INVALID — the card does not exist / does not belong to your partnership.

③ Activating the physical card

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

Activates the physical card; the prerequisite is that the card has shipped. The endpoint is idempotent — repeated calls return the same success.

Request parameters and response

Request parameters: companyId (String, required, ≤36; the requesting company ID) and cardId (String, required, ≤32; the card id). This is an action endpoint: data is null.

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

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

Error codes

Error code	Description
`CARD_INVALID`	The card does not exist / does not belong to your partnership
`CARD_NOT_SHIPPED`	The card has not shipped yet and cannot be activated

Related webhook: CARD_ACTIVATED.

④ Setting the PIN

POST /open-api-corp/card/v1/set-pin

Sets the physical card’s PIN; the prerequisite is that the physical card has been activated.

The PIN and the identity-check fields are AES-GCM encrypted with your SK before upload — the same crypto contract as retrieve-secure-card, in the opposite direction (for the contract see Retrieving secure card details: AES/GCM/NoPadding, 128-bit tag, keyed with the SK).

Request parameters

Field	Type	Required	Description
`companyId`	String	Yes	≤50; the requesting company ID
`cardId`	String	Yes	≤50; the card id
`encryptedPin`	String	Yes	The encrypted PIN (AES-GCM under the partner key; the clear PIN must be 4 digits, no sequential runs, no all-identical digits)
`encryptedCvv2`	String	Yes	The encrypted CVV2 (identity check)
`encryptedExpireDate`	String	Yes	The encrypted expiry (identity check; plaintext format mm/yy)
`encryptedPanLast4`	String	Yes	The encrypted last four digits of the PAN (identity check)
`iv`	String	Yes	The per-call random IV (Base64); the 4 ciphertext fields share the same `iv`

Request and response examples

{
  "companyId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "cardId": "5185740066240790530",
  "encryptedPin": "UGluTW9ja0NpcGhlclRleHQrVGFnMTZC",
  "encryptedCvv2": "Q3Z2Mk1vY2tDaXBoZXJUZXh0K1RhZzE2Qg==",
  "encryptedExpireDate": "RXhwTW9ja0NpcGhlclRleHQrVGFnMTZC",
  "encryptedPanLast4": "TGFzdDRNb2NrQ2lwaGVyVGV4dCtUYWcxNkI=",
  "iv": "MTIzNDU2Nzg5MGFi"
}

The response data carries cardId and success (Boolean, whether the PIN was set):

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "cardId": "5185740066240790530",
    "success": true
  }
}

Error codes

Error code	Description
`CARD_INVALID`	The card does not exist / does not belong to your partnership
`CARD_NOT_ACTIVATED`	The card is not activated; the PIN cannot be set
`CARD_STATE_INVALID`	The card state does not allow setting a PIN; only ACTIVE / FROZEN
`PIN_RULE_VIOLATION`	The PIN is not 4 digits / is a sequential run / is all-identical digits

Next steps

No upgradable virtual card yet? Issue one first: Applying for a virtual card
Card states and the freeze capability domains: State machines and freezing

​📄 Guide

​① Upgrade application: virtual to physical

​Request parameters

​Response data

​Request and response examples

​Error codes

​② Tracking production and shipping

​Request parameters

​Response data

​Response examples (shipped / not shipped)

​③ Activating the physical card

​Request parameters and response

​Error codes

​④ Setting the PIN

​Request parameters

​Request and response examples

​Error codes

​Next steps

📄 Guide

① Upgrade application: virtual to physical

Request parameters

Response data

Request and response examples

Error codes

② Tracking production and shipping

Request parameters

Response data

Response examples (shipped / not shipped)

③ Activating the physical card

Request parameters and response

Error codes

④ Setting the PIN

Request parameters

Request and response examples

Error codes

Next steps