> 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/central-issuance/implement-central-issuance/tracking-hub.md).

# Tracking hub

Use tracking hub to receive production, shipment, or return updates for a physical card produced outside Thales D1.

### Flow

<figure><img src="https://1428240856-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWhgSoXgpjZJxLx4cDHB1%2Fuploads%2FNjRJPrU3dVmG5dtZzkxs%2FFlow%20-%20Tracking%20hub.png?alt=media&amp;token=6f903df1-c583-4b85-bec6-48f7ed04bdf5" alt=""><figcaption></figcaption></figure>

1. Issuer back-end request to track the card
2. D1 Connects to carriers to retrieve shipment information
3. Carriers sends regular shipment statuses
4. D1 formats and sends the statuses to Issuer back-end

### Sequence diagram

<figure><img src="https://1428240856-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWhgSoXgpjZJxLx4cDHB1%2Fuploads%2FOQVZsRRqt9pc0RP53NUM%2FSequence%20Diagram%20-%20Tracking%20hub.svg?alt=media&amp;token=97f216c7-a1fb-4044-a961-8f81a4fd894a" alt=""><figcaption></figcaption></figure>

### How it works

{% tabs %}
{% tab title="PRODUCTION" %}

* Use `trackingType = PRODUCTION` to receive a production completion update.
* Thales D1 sends one notification with `status = SUCCESSFUL`.
* The notification includes `details.status = CARD_SHIPPED`.
  {% endtab %}

{% tab title="SHIPMENT" %}

* Use `trackingType = SHIPMENT` to receive shipment progress updates.
* Thales D1 first sends a notification with `status = PENDING`.
* Thales D1 then sends one or more notifications with `status = SUCCESSFUL` as shipment data changes.
* When available, the notification includes `details.shipment`. See [Track shipment](/central-issuance/implement-central-issuance/card-order-tracking/track-shipment.md).
  {% endtab %}

{% tab title="RETURN" %}

* Use `trackingType = RETURN` to receive a returned-card update.
* Thales D1 sends one notification with `status = SUCCESSFUL`.
* The notification includes `details.status = CARD_RETURNED`.
  {% endtab %}
  {% endtabs %}

### Required APIs

| API                                                                                                                                                        | Inbound/Outbound    | Description                                                           |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | --------------------------------------------------------------------- |
| [Tracking hub](/central-issuance/integrate-d1-api/d1-api-reference/inbound-api-to-d1/tracking-hub-api.md#post-issuers-issuerid-physicalcards-cardid-track) | Issuer -> Thales D1 | Request production, shipment, or return tracking for a physical card. |
| [Notifications](/central-issuance/integrate-d1-api/d1-api-reference/outbound-api-from-d1/card-api.md#post-notifications-d1-v2-issuers-issuerid-cards)      | Issuer <- Thales D1 | Receive notifications for the `STANDALONE_TRACKING` operation.        |

### API Inputs

Required D1 API inputs:

* `issuerId`: Unique identifier of the issuer.
* `cardId`: Unique identifier of the card.
* `trackingType`: Type of tracking to perform. Supported values are `PRODUCTION`, `SHIPMENT`, and `RETURN`.

#### Examples

**Tracking type = PRODUCTION**

```json
{
  "trackingType": "PRODUCTION",
  "productionSite": "London"
}
```

**Tracking type = SHIPMENT**

```json
{
  "trackingType": "SHIPMENT",
  "trackingNumber": "61293150000079650811",
  "shipmentDate": "2023-01-21T17:32:28Z",
  "productionSite": "London",
  "postalCode": "WC2N5DU",
  "countryCode": "GB"
}
```

**Tracking type = RETURN**

```json
{
  "trackingType": "RETURN",
  "productionSite": "London"
}
```

### Track the result

Consume notifications on the `STANDALONE_TRACKING` operation.

Key fields:

* `operation`: Always `STANDALONE_TRACKING`.
* `status`: Operation status. Values are `PENDING`, `SUCCESSFUL`, or `FAILED`.
* `cardId`: Card identifier used in the request.
* `details.trackingType`: `PRODUCTION`, `SHIPMENT`, or `RETURN`.
* `details.productionSite`: Production site identifier, when available.
* `details.status`: Tracking result, such as `CARD_SHIPPED` or `CARD_RETURNED`.
* `details.shipment`: Shipment tracking details for `SHIPMENT` updates. See [Track shipment](/central-issuance/implement-central-issuance/card-order-tracking/track-shipment.md).

Top-level `status` is the operation status.

`details.status` is the business tracking status.

{% hint style="info" %}
Notifications can arrive more than once, and they can arrive out of order. Use `operationId` to de-duplicate events.
{% endhint %}

Notification sequence by tracking type:

| trackingType | Notifications sent                                                                                                                        |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `PRODUCTION` | One notification with `status = SUCCESSFUL` and `details.status = CARD_SHIPPED`.                                                          |
| `RETURN`     | One notification with `status = SUCCESSFUL` and `details.status = CARD_RETURNED`.                                                         |
| `SHIPMENT`   | One notification with `status = PENDING`, then one or more notifications with `status = SUCCESSFUL` as shipment updates become available. |

#### Notification examples

**Tracking type = PRODUCTION**

```json
{
  "operationId": "op-7a3f2c1e-9b4d-4f8a-bc12-1a2b3c4d5e6f",
  "operation": "STANDALONE_TRACKING",
  "status": "SUCCESSFUL",
  "issuerId": "issuer-001",
  "cardId": "c-9f8e7d6c5b4a",
  "timestamp": "2026-05-22T09:38:00Z",
  "details": {
    "trackingType": "PRODUCTION",
    "productionSite": "PERSO-CENTER-FR-01",
    "status": "CARD_SHIPPED"
  }
}
```

**Tracking type = SHIPMENT — first notification**&#x20;

```json
{
  "operationId": "op-7a3f2c1e-9b4d-4f8a-bc12-1a2b3c4d5e6f",
  "operation": "STANDALONE_TRACKING",
  "status": "PENDING",
  "issuerId": "issuer-001",
  "cardId": "c-9f8e7d6c5b4a",
  "timestamp": "2026-05-22T09:38:05Z",
  "details": {
    "trackingType": "SHIPMENT",
    "productionSite": "PERSO-CENTER-FR-01",
    "status": "CARD_SHIPPED"
  }
}
```

**Tracking type = SHIPMENT — subsequent notification (with shipment details)**

```json
{
  "operationId": "op-7a3f2c1e-9b4d-4f8a-bc12-1a2b3c4d5e6f",
  "operation": "STANDALONE_TRACKING",
  "status": "SUCCESSFUL",
  "issuerId": "issuer-001",
  "cardId": "c-9f8e7d6c5b4a",
  "timestamp": "2026-05-22T14:12:33Z",
  "details": {
    "trackingType": "SHIPMENT",
    "productionSite": "PERSO-CENTER-FR-01",
    "status": "CARD_SHIPPED",
    "shipment": {
      "carrier": "fedex",
      "trackingNumber": "1234567890",
      "status": "IN_TRANSIT",
      "message": "In transit",
      "trackingUrl": "https://www.fedex.com/track?trk=1234567890",
      "estimatedDeliveryDate": "2026-05-24T00:00:00Z",
      "lastUpdatedAt": "2026-05-22T13:55:00Z",
      "lastCheckpoint": {
        "checkpointTime": "2026-05-22T13:55:00Z",
        "city": "Paris",
        "countryName": "France",
        "message": "Arrived at facility"
      }
    }
  }
}
```

**Tracking type = RETURN**

```json
{
  "operationId": "op-7a3f2c1e-9b4d-4f8a-bc12-1a2b3c4d5e6f",
  "operation": "STANDALONE_TRACKING",
  "status": "SUCCESSFUL",
  "issuerId": "issuer-001",
  "cardId": "c-9f8e7d6c5b4a",
  "timestamp": "2026-05-25T10:02:11Z",
  "details": {
    "trackingType": "RETURN",
    "productionSite": "PERSO-CENTER-FR-01",
    "status": "CARD_RETURNED"
  }
}
```


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.payments.thalescloud.io/central-issuance/implement-central-issuance/tracking-hub.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.