> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedecard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Physical Card Shipping

> Explains the shipping status state machine for physical cards, the shipping information query endpoint, and the real-time WebSocket push; it also marks the boundaries of the shipping capability in the DeCard-Managed model.

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

<Warning>
  **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.
</Warning>

***

## 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](../how-to-use/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.

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/en/diagrams/va-shipping-states-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=dd166e24e3640b49da5fee63789238cb" alt="Physical card shipping states" width="524" height="236" data-path="imgs/en/diagrams/va-shipping-states-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/en/diagrams/va-shipping-states-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=6d54d9f28a324f132ffe317fff88914d" alt="Physical card shipping states" width="524" height="236" data-path="imgs/en/diagrams/va-shipping-states-dark.svg" />
</Frame>

***

## 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

```bash theme={null}
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](../integration-resources/overview). 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)    |

<Warning>
  `cardId` is a **string**, not a number, so write it as a string in your examples.
</Warning>

### Response example (masked placeholders)

```json theme={null}
{
  "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](../how-to-use/managing-cards/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`).

<Note>
  The WebSocket handshake, authentication, and full data structures are consolidated on the [Integration Resources › Webhook and WebSocket Real-Time Notifications](../integration-resources/webhook-websocket) page; the payload fields for this message type are in the [`CARD_PHYSICAL_SHIPPING` physical card shipping information](../integration-resources/webhook-websocket#3-4-card_physical_shipping-physical-card-shipping-information) section of that page (`messageType` = `CARD_PHYSICAL_SHIPPING`).
</Note>

***

## Next steps

* To **apply for, activate, or set the PIN of** a physical card (H5 guidance page), see [Issuing Cards](../how-to-use/managing-cards/issuing-cards).
* For overall card status and the `physicalCardStatus` state machine, see [Managing Cards · Overview](../how-to-use/managing-cards/overview).
* For WebSocket and webhook connectivity and the full data structures, see [Integration Resources › Webhook and WebSocket Real-Time Notifications](../integration-resources/webhook-websocket).