Physical Card Shipping - DCS Technical Documentation

📄 Overview

A physical card enters the production and shipping flow as soon as the user’s application succeeds. The system keeps one shipping tracking record per physical card and advances it through a fixed state machine. You can query the current status at any time, and once the card reaches the shipping stage you also get the tracking number and the carrier name. Status changes are pushed in real time over WebSocket as well (see below).

Capability boundary (important): for physical card shipping, the DeCard-Managed model exposes a single read-only query endpoint (status, tracking number, and carrier). It does not provide shipping quotes, per-country rate tables, shipping method selection, delivery address changes, batch shipping, metal card surcharges, or similar capabilities. Confirm delivery lead times, shipping fees, and address-change policy with DCS during integration.

Shipping status state machine

Physical card shipping advances through the following four states in strict order:

Status code	Name	Meaning
PENDING_EMBOSSING	Pending embossing	The user has applied for a physical card and the system has created a shipping tracking record, waiting for embossing to start
EMBOSSING_IN_PROGRESS	Embossing in progress	The physical card is being produced; the production system has generated and is processing the embossing file
IN_DELIVERY	In delivery	The physical card has been produced and handed to the carrier; the tracking number and carrier name are returned from this point on
DELIVERY_COMPLETE	Delivery complete	The physical card has been delivered and the shipping flow is closed (whether it has been activated is reflected in `physicalCardStatus`, not here)

Transitions follow a strict sequence: PENDING_EMBOSSING → EMBOSSING_IN_PROGRESS → IN_DELIVERY → DELIVERY_COMPLETE. trackingNumber and trackingCompanyName are populated only after the card reaches IN_DELIVERY.

This shipping state machine and the card’s physicalCardStatus (UN_APPLY / INACTIVE / ACTIVE / REPLACE / FROZEN / CANCELLED, see Managing Cards · Overview) are two separate status fields: the former describes where the card sits in the shipping chain, the latter describes whether the card itself is usable. Do not mix them up.

Query shipping information

Preconditions

The card is a physical card and has been applied for successfully, so a shipping tracking record exists. A virtual card, or a card for which no physical card has been requested, has no matching record.
You already hold the user’s externalUserId and the target card’s cardId.

Endpoint

Endpoint	Query parameters	Description
`GET /card/v2/physical-shipping-info`	`externalUserId` (required), `cardId` (required, string)	Identifies the card precisely by card ID

Request example

curl -X GET "{{dicard-server}}/card/v2/physical-shipping-info?externalUserId=<EXTERNAL_USER_ID>&cardId=<CARD_ID>" \
  -H "Content-Type: application/json"

The request must carry the authentication headers (X-DAPI-API-KEY / X-DAPI-SIGN / X-DAPI-TIMESTAMP / X-DAPI-NONCE); see Integration Resources › Authentication Guide. In the example, <EXTERNAL_USER_ID> and <CARD_ID> are placeholders that you replace with real values. Never write real PII into examples.

Response fields (`data`)

Field	Type	Description
`cardId`	string	Card ID
`externalUserId`	string	External user ID
`cardMantissa`	string	Last four digits of the card number
`status`	string	Shipping status; see the state machine above
`trackingNumber`	string	Tracking number (populated only from `IN_DELIVERY` onwards)
`trackingCompanyName`	string	Carrier name (populated only from `IN_DELIVERY` onwards)

cardId is a string, not a number, so write it as a string in your examples.

Response example (masked placeholders)

{
  "code": "SYS_SUCCESS",
  "message": "",
  "messageDetail": null,
  "data": {
    "cardId": "<CARD_ID>",
    "externalUserId": "<EXTERNAL_USER_ID>",
    "cardMantissa": "<LAST_4>",
    "status": "IN_DELIVERY",
    "trackingNumber": "<TRACKING_NO>",
    "trackingCompanyName": "<CARRIER_NAME>"
  }
}

The response envelope is always { code, message, messageDetail, data } (there is no success boolean), and the success literal for code is SYS_SUCCESS (consistent across this documentation set). On success, messageDetail is usually null.

Error handling

Scenario	What you see and what to do
The card is not a physical card, or no physical card has been requested	There is no shipping tracking record, so `data` is empty or carries no `status`. First confirm that the physical card application has been completed through the H5 page (see Issuing Cards)
The card has not reached the shipping stage yet	While `status` is `PENDING_EMBOSSING` or `EMBOSSING_IN_PROGRESS`, `trackingNumber` and `trackingCompanyName` are empty. This is expected, so do not retry
Missing parameter, or the card does not belong to that user	The request fails; judge from the response `code` and `message`. `externalUserId` and `cardId` (or `cardMantissa`) must resolve to a card held by the same user

Real-time WebSocket notifications

Besides querying on demand, DCS pushes a real-time WebSocket notification whenever the shipping status changes (a signature capability of the DeCard-Managed model), so you learn the latest progress without polling.

When a push is sent

When the shipping tracking record is created
When the shipping status changes
When the shipping information (tracking number or carrier) is updated

Message type and data structure

The WebSocket message type is CARD_PHYSICAL_SHIPPING, and its payload fields match the response fields above (cardId / externalUserId / cardMantissa / status / trackingNumber / trackingCompanyName).

The WebSocket handshake, authentication, and full data structures are consolidated on the Integration Resources › Webhook and WebSocket Real-Time Notifications page; the payload fields for this message type are in the CARD_PHYSICAL_SHIPPING physical card shipping information section of that page (messageType = CARD_PHYSICAL_SHIPPING).

Next steps

To apply for, activate, or set the PIN of a physical card (H5 guidance page), see Issuing Cards.
For overall card status and the physicalCardStatus state machine, see Managing Cards · Overview.
For WebSocket and webhook connectivity and the full data structures, see Integration Resources › Webhook and WebSocket Real-Time Notifications.

​📄 Overview

​Shipping status state machine

​Query shipping information

​Preconditions

​Endpoint

​Request example

​Response fields (data)

​Response example (masked placeholders)

​Error handling

​Real-time WebSocket notifications

​When a push is sent

​Message type and data structure

​Next steps

📄 Overview

Shipping status state machine

Query shipping information

Preconditions

Endpoint

Request example

Response fields (`data`)

Response example (masked placeholders)

Error handling

Real-time WebSocket notifications

When a push is sent

Message type and data structure

Next steps