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

> Redundant screenshots removed.

## 📄 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](./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.

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/en/diagrams/pa-physical-issue-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=a52b4c7044598106b15dc5d93e8512b1" alt="Virtual-to-physical card order sequence" width="638" height="610" data-path="imgs/en/diagrams/pa-physical-issue-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/en/diagrams/pa-physical-issue-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=33ea1fa962224e4f14cb8d339a731226" alt="Virtual-to-physical card order sequence" width="638" height="610" data-path="imgs/en/diagrams/pa-physical-issue-dark.svg" />
</Frame>

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

Minimum request body:

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

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/en/diagrams/pa-physical-activate-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=bc655bd8012f3154bec538855c917671" alt="Physical card activation sequence" width="476" height="318" data-path="imgs/en/diagrams/pa-physical-activate-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/en/diagrams/pa-physical-activate-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=606e85d73d81a46daaa5f18f115c4018" alt="Physical card activation sequence" width="476" height="318" data-path="imgs/en/diagrams/pa-physical-activate-dark.svg" />
</Frame>

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

Request body:

```json theme={null}
{
  "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](./card-management).

## Next steps

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