> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/d1-v1-api/migrate-to-d1-api-v2.md).

# Migrate to D1 API v2

## Migrate end users and cards to V2 APIs

In D1, two generations of APIs are available: V1 and V2.

V2 introduces new capabilities, such as Authorization Controls APIs (for example, the limits control API).

{% hint style="info" %}
This page is for issuers that already have end users ("consumers" in the D1 API) and cards registered through the V1 APIs and want to migrate them to V2 in order to use the new V2 features.
{% endhint %}

### Migration steps <a href="#migration-steps" id="migration-steps"></a>

A V1 to V2 migration consists of four steps. Some steps are handled by Thales; others by the issuer.

<table><thead><tr><th width="100">Step</th><th width="100">Owner</th><th>Description</th></tr></thead><tbody><tr><td>1</td><td>Thales</td><td>Thales configures your issuer tenant for V1-to-V2 migration. This configuration has no impact on your existing issuer backend integrations or live traffic.</td></tr><tr><td>2</td><td>Issuer</td><td>The issuer integrates the V2 Register consumer API and the V2 Register card API, and routes all new registration traffic to these V2 APIs. As a result, every new end user and card is created directly in V2. The issuer can continue to use all other V1 APIs, including for cards that were registered through V2.</td></tr><tr><td>3</td><td>Thales</td><td>Thales runs the bulk migration process. All end users and cards that were previously registered in V1 for this issuer are migrated to V2. The issuer can continue to use V1 APIs, including for cards that have already been migrated to V2.</td></tr><tr><td>4</td><td>Issuer</td><td>The issuer integrates the remaining V2 lifecycle APIs for end users and cards — suspend, resume, renew, replace, and delete for cards, and delete for end users — and routes all lifecycle traffic to these V2 APIs.</td></tr></tbody></table>

## Migration limitations <a href="#migration-limitations" id="migration-limitations"></a>

Several behavioral changes and limitations apply during a V1 to V2 migration.

### Data mapping <a href="#data-mapping" id="data-mapping"></a>

The data models used by the V1 and V2 APIs differ for some attributes. During migration, specific V1 values are automatically converted to the corresponding V2 values.

| Attribute      | V1 API   | V1 value  | V2 API   | V2 value after migration                                                              |
| -------------- | -------- | --------- | -------- | ------------------------------------------------------------------------------------- |
| Consumer state | Consumer | INACTIVE  | Consumer | ACTIVE (INACTIVE is not supported in V2; migrated consumers are set to ACTIVE).       |
| Consumer state | Consumer | ACTIVE    | Consumer | ACTIVE                                                                                |
| Card state     | Card     | INACTIVE  | Card     | SUSPENDED                                                                             |
| Card state     | Card     | ACTIVE    | Card     | ACTIVE                                                                                |
| Card accountId | Card     | accountId | N/A      | `consumerId` (replaces the V1 `accountId` value with the corresponding `consumerId`). |
| Card name      | N/A      | N/A       | Card     | Empty string (no card name is populated during migration).                            |

### Scheme limitation <a href="#scheme-limitation" id="scheme-limitation"></a>

Only Mastercard and Visa cards are supported in V2. Cards from other payment networks that exist in V1 are not migrated to V2.

### `cardId` and PAN limitation <a href="#cardid-and-pan-limitation" id="cardid-and-pan-limitation"></a>

In the V2 APIs, a `cardId` is associated with exactly one PAN. It is a one-to-one mapping.

In V1, multiple `cardId` values can be linked to the same PAN. During migration:

* Only the most recent `cardId` for a given PAN is migrated to V2 ("most recent card wins").
* Older `cardId` values associated with the same PAN are not migrated and are not supported in V2.
* If you call a V2 API with one of these non-migrated `cardId` values, the API returns HTTP `404 Not Found`.

### V1 Renew API vs V2 Renew and Replace APIs <a href="#v1-renew-api-vs-v2-renew-and-replace-api-limitation" id="v1-renew-api-vs-v2-renew-and-replace-api-limitation"></a>

This limitation applies only when the [V1 Renew](/d1-v1-api/d1-v1-api-references/card-operations/inbound/operations.md#post-issuers-issuerid-cards-cardid-operations-renew) API is called on a card that has already been migrated to V2 (for example, after Thales has started the migration but before the issuer has fully implemented the V2 Renew and V2 Replace APIs).

In this situation, the V1 Renew API returns HTTP `403 Forbidden` if any of the following conditions are met:

* The `newCardId` in the payload is equal to the existing `cardId`, but the card PAN has been updated.
* The `newCardId` in the payload is not equal to the existing `cardId`, but the card PAN is still the same.
* The `newCardId` in the payload is not equal to the existing `cardId` and `newCardStatus` is `INACTIVE`.
* The `reasonCode` provided in the payload is not allowed in V2.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.payments.thalescloud.io/d1-v1-api/migrate-to-d1-api-v2.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.