Physical card - DCS Technical Documentation

📄 Guide

Whether you serve high-net-worth cardholders, frequent travellers or in-store spending, the Partner-Managed model lets you issue your end users a DCS physical card: a Visa card that works at merchants, ATMs and digital wallets worldwide. Physical and virtual cards share the same issuing, KYC, authorization and clearing flows; all that differs is the plastic itself, the shipping step and the activation step. A physical card is a tangible payment instrument with an EMV chip and contactless (NFC) support, printed with the card number, the expiry date and the card identification data, and accepted at more than 99% of in-store acceptance points. The card art can be branded (embossed name, an enterprise card layout code), which helps you carry your brand into your cardholder’s wallet.

Physical card vs virtual card

Dimension	Physical card	Virtual card
Form	Tangible card (plastic or metal)	Digital credentials only
Main use cases	In-store POS, ATM withdrawals, travel	Online shopping, subscriptions, digital advertising
How it is obtained	Shipped after application, needs activation	Issued instantly online, active immediately
Digital wallets	Apple Pay and Google Pay supported	Supported (see Push provisioning)
Our recommendation	Complementary to the virtual card, combine them by use case	—

Physical and virtual cards complement each other rather than compete. Let your end users cover online payments and subscriptions with a virtual card, and in-store spending and travel with a physical one.

How to issue a physical card to a user

A DCS physical card comes out of a virtual-to-physical order: the cardholder has a virtual card first, and you then raise a conversion order against that card carrying the shipping address and the card art details.

Endpoint: POST /open-api/card-order/v1/virtual-to-physical (who does it: the partner raises the order) Minimum request body:

{
  "cardOrderRef": "your-idempotent-ref",
  "replaceCardId": "the cardId of the virtual card being replaced",
  "virtualToPhysicalInfo": {
    "countryCode": "SG",
    "state": "Singapore",
    "city": "Singapore",
    "postalCode": "049315",
    "address": "1 Raffles Place",
    "embossingName": "TOM LEE",
    "cardLayoutCode": "ABC123",
    "needShippingInfo": true
  }
}

Request fields (an extract; the API reference carries the full constraints):

Field	Type	Required	Description
`cardOrderRef`	string	Yes	Card order idempotency key, max length 50
`replaceCardId`	string	Yes	The `cardId` of the virtual card being replaced, max length 50
`virtualToPhysicalInfo.countryCode`	string	Yes	Destination country code, 2-letter ISO (SG, US, CN and so on)
`virtualToPhysicalInfo.state`	string	Yes	State or province, max length 20
`virtualToPhysicalInfo.city`	string	Yes	City, max length 20
`virtualToPhysicalInfo.postalCode`	string	Yes	Postal code, max length 10
`virtualToPhysicalInfo.address`	string	Yes	Address, max length 40
`virtualToPhysicalInfo.address2` / `address3`	string	No	Additional address lines, max length 40 each
`virtualToPhysicalInfo.embossingName`	string	Yes	The name embossed on the card, max length 26
`virtualToPhysicalInfo.cardLayoutCode`	string	Yes	Card layout code, max length 6 (supplied by DCS when the card profile is set up)
`virtualToPhysicalInfo.needShippingInfo`	boolean	Yes	Whether DCS should ship the card on your behalf
`virtualToPhysicalInfo.mailMobileCode`	string	No	Country code of the delivery contact number (2-letter ISO, SG for example)
`virtualToPhysicalInfo.mailMobile`	string	No	Delivery contact number (91159519, for example)

Virtual-to-physical conversion is rate-limited within a 24-hour window; exceeding it returns DAPI_VIRTUAL_TO_PHYSICAL_APPLY_LIMIT_EXCEEDED, so back off before retrying.

Keep the shipping address to Latin characters, digits and basic punctuation. Non-Latin characters (Chinese, Arabic and so on) can fail the card network’s shipping validation, so transliterate them into Latin script before you submit.

A successful response returns a card order. The key fields are:

Field	Description
`cardOrderId`	Card order ID
`type`	Order type, `VIRTUAL_TO_PHYSICAL` here
`cardId`	Card ID
`replaceCardId`	The `cardId` of the virtual card that was replaced
`status`	Order status: `PENDING / PHYSICAL_SETTING_COMPLETED / COMPLETED / FAILED`
`errorCode` / `errorReason`	Failure code and reason when the order fails

The final status on success: a card order succeeds with COMPLETED, and whether cardId carries a value is a useful cross-check. PHYSICAL_SETTING_COMPLETED is an intermediate step in the conversion, not a final status (the final statuses are COMPLETED and FAILED). Every endpoint returns the same envelope, { code, message, messageDetail, data }; for what its fields mean, the success value of code and the error code dictionary, see Authentication and security. Physical card delivery times and fees follow the card profile agreed with DCS and are currently not returned in any endpoint response or webhook.

⚠️ How the old and new cards relate (must read)

Once the virtual-to-physical order completes, the same cardholder has two cardIds. This section decides which cardId you use before and after activation, and which card an authorization is booked against:

	Description
cardId	The physical card gets a new `cardId`, different from the original virtual card. Store it separately
Card number (PAN)	The physical card carries the same PAN as the original virtual card. This is not a re-numbering, just an additional physical carrier
Before activation	The physical card is `PENDING_ACTIVATION` and unusable; the original virtual card still works and all authorizations still belong to it
After activation	The original virtual card is terminated automatically (`INVALID`), and from then on all authorizations belong to the physical card

Activation is therefore a switch-over point. Once activation succeeds, move the cardId you use for queries, freezes, limit lookups and everything else from the virtual card to the physical card, and note that the original virtual card turning INVALID is expected behavior, not a fault.

How to activate a physical card

A physical card has to be activated once it arrives before it can be used; a virtual card is active from the start and skips this step.

Endpoint: POST /open-api/card/v1/physical-active (who does it: the partner calls it once the cardholder has the card) Request body:

{
  "cardId": "the cardId of the physical card"
}

Field	Type	Required	Description
`cardId`	string	Yes	Card ID, max length 50

On success the card status moves from PENDING_ACTIVATION to ACTIVATED, and the response data also returns type (PHYSICAL), panFirst6 and panLast4. Card status transitions and freeze, unfreeze and replacement are covered in Card management.

Next steps

With the physical card issued, go to Card management for freeze and unfreeze, PIN and replacement operations; to push the physical card into Apple Pay or Google Pay, see Push provisioning.

​📄 Guide

​Physical card vs virtual card

​How to issue a physical card to a user

​⚠️ How the old and new cards relate (must read)

​How to activate a physical card

​Next steps