Card Order Tracking

D1 sends real-time production and shipment updates for physical cards to the issuer backend. You can receive updates asynchronously through notifications (webhooks) or retrieve the latest status on demand.

How it works

Use one or both approaches:

Receive webhook notifications for each production step and shipment update.
Handle at-least-once delivery. Expect retries and duplicate events.
Implement the callback endpoint defined by D1 event & message notification.
Expose the Notify Card Operations API on your issuer backend.

Query the current production/shipment status at any time.
Call the Get Card Issuance Status API with the card identifier.

Recommended integration

Persist status per card

Store the latest known details.status for each cardId.

Process notifications first

Handle duplicates and out-of-order delivery. Use operationId plus timestamps for reconciliation.

Reconcile on demand when needed

Call Get Card Issuance Status after missed events. Call it for user-driven refresh in the issuer application.

Expose user-facing tracking

Show carrier tracking when details.shipment.trackingUrl is present. Fall back to internal status when it is not present.

Delivery and idempotency

Notifications can arrive out of order, and more than once.

Use operationId to de-duplicate and correlate events.
Use startTime/endTime to decide which event is the latest for a given operation.
Use the on-demand API to reconcile state if you detect gaps.

Common parameters

Each notification and on-demand response can include:

Field

Description

Availability

operationId

Unique identifier for the operation instance. Use for idempotency and correlation.

Always

operation

Operation type. Always PRODUCE for physical issuance tracking.

Always

status

Operation status: PENDING, SUCCESSFUL, or FAILED.

Always

startTime

ISO 8601 timestamp when the operation started.

Always

endTime

ISO 8601 timestamp when the operation completed.

Conditional (when completed)

cardId

Internal card identifier in D1.

Always

details

Issuance-specific payload for the operation.

Always

errorCode

Machine-readable failure cause.

Conditional (on failure)

error

Short human-readable failure description.

Conditional (on failure)

inputFileName

File name containing card issuance requests.

Conditional (file-based orders only)

issuerRequestId

Request correlation identifier from the input file.

Conditional (file-based orders only)

Top-level status is the operation status. details.status is the physical issuance status.

Parameters specific to physical issuance (details)

The physical issuance payload is in details for the PRODUCE operation.

Physical card issuance status

Status code

Description

CARD_PROD_REQUESTED

Card personalization has been requested via the D1 APIs.

DATA_PREPARED

Data has been successfully processed.

CARD_PROD_READY

Data has been sent to the personalization center, and the card is ready for personalization.

CARD_PROD_ONGOING

Card personalization is in progress.

CARD_SHIPPED

The card has been handed over to the carrier.

DATA_EXCEPTION

An error occurred during data processing.

CARD_PROD_EXCEPTION

Card personalization encountered an issue.

CARD_PROD_CANCELED

Card personalization was canceled by the issuer.

CARD_PROD_ONHOLD

Card personalization is on hold, either by the issuer or due to an issue with the shipment address.

Details object

Field

Description

Availability

reason

Additional details in case of exception during data processing or card production.

On exceptions

consumerId

Deprecated. Use your internal End user identifier.

Deprecated

dueDate

Estimated shipment date, calculated upon receipt of the card issuance request.

After data processing

productionSite

The name of the personalization center handling the card personalization.

After data processing

shipment

Shipment tracking details, available only when provided by the carrier.

After shipment

inputFileName

Name of the file containing card issuance requests.

Only for cards ordered by file

issuerRequestId

Unique identifier for the card issuance request from the input file.

Only for cards ordered by file

Shipment object

When present, details.shipment can include:

carrier: Lowercase carrier code (for example, fedex).
trackingNumber: Carrier tracking reference.
status: Carrier shipment status (when provided by the carrier).
message: Human-readable carrier status (when provided by the carrier).
trackingUrl: Direct URL to carrier tracking with the tracking number embedded.
redirectUrl: Carrier landing page URL that may handle locale/consent flows.
pickupDate: ISO 8601 timestamp when the carrier collected the parcel.
estimatedDeliveryDate: ISO 8601 estimated delivery time.
lastUpdatedAt: ISO 8601 timestamp of the last tracking event.
lastCheckpoint:
- checkpointTime: ISO 8601 timestamp.
- city: Last checkpoint city.
- countryName: Country of the last checkpoint.
- message: Human-readable checkpoint status.

dueDate (production estimate) differs from estimatedDeliveryDate (carrier estimate). Carrier fields are conditional and depend on the carrier integration.

Examples by issuance status

{
  "operations": [
    {
      "operationId": "01c5a05e-e197-11ec-8fea-0242ac120002",
      "operation": "PRODUCE",
      "status": "PENDING",
      "startTime": "2025-01-17T06:28:02.492Z",
      "cardId": "271b-6e47-8ec3-7f3f",
      "details": {
        "status": "CARD_PROD_REQUESTED"
      }
    }
  ]
}

{
  "operations": [
    {
      "operationId": "01c5a05e-e197-11ec-8fea-0242ac120002",
      "operation": "PRODUCE",
      "status": "PENDING",
      "startTime": "2025-01-17T06:28:02.492Z",
      "cardId": "271b-6e47-8ec3-7f3f",
      "details": {
        "status": "DATA_PREPARED",
        "dueDate": "2025-01-21",
        "productionSite": "Gemenos"
      }
    }
  ]
}

{
  "operations": [
    {
      "operationId": "01c5a05e-e197-11ec-8fea-0242ac120002",
      "operation": "PRODUCE",
      "status": "FAILED",
      "startTime": "2025-01-17T06:28:02.492Z",
      "endTime": "2025-01-21T09:28:12.492Z",
      "cardId": "271b-6e47-8ec3-7f3f",
      "details": {
        "status": "DATA_EXCEPTION"
      },
      "errorCode": "FIELD_INVALID_FORMAT",
      "error": "pan"
    }
  ]
}

{
  "operations": [
    {
      "operationId": "01c5a05e-e197-11ec-8fea-0242ac120002",
      "operation": "PRODUCE",
      "status": "SUCCESSFUL",
      "startTime": "2025-01-17T06:28:02.492Z",
      "endTime": "2025-01-21T09:28:12.492Z",
      "cardId": "271b-6e47-8ec3-7f3f",
      "details": {
        "status": "CARD_SHIPPED",
        "dueDate": "2025-01-21",
        "productionSite": "Gemenos",
        "shipment": {
          "estimatedDeliveryDate": "2025-01-21T17:32:28Z"
        }
      }
    }
  ]
}

{
  "operations": [
    {
      "operationId": "01c5a05e-e197-11ec-8fea-0242ac120002",
      "operation": "PRODUCE",
      "status": "SUCCESSFUL",
      "startTime": "2025-01-17T06:28:02.492Z",
      "endTime": "2025-01-21T09:28:12.492Z",
      "cardId": "271b-6e47-8ec3-7f3f",
      "details": {
        "status": "CARD_SHIPPED",
        "dueDate": "2025-01-21",
        "productionSite": "Gemenos",
        "shipment": {
          "pickupDate": "2025-01-21T17:32:28Z",
          "carrier": "fedex",
          "trackingNumber": "61293150000079650811",
          "status": "IN_TRANSIT",
          "message": "In transit",
          "trackingUrl": "https://www.fedex.com/apps/fedextrack/?tracknumbers=61293150000079650811&cntry_code=US",
          "redirectUrl": "https://www.fedex.com/apps/fedextrack/?action=track&tracknumbers=61293150000079650811&cntry_code=US",
          "estimatedDeliveryDate": "2025-01-21T17:32:28Z",
          "lastUpdatedAt": "2025-01-21T17:32:28Z",
          "lastCheckpoint": {
            "checkpointTime": "2025-01-21T17:32:28Z",
            "city": "New York",
            "countryName": "United States",
            "message": "Arrived at facility"
          }
        }
      }
    }
  ]
}

Sequence

This diagram shows typical transitions from request to shipment, including exception and on-hold paths.

Physical card issuance tracking on demand

The issuer backend can retrieve the card production status on demand using the Get Card Issuance Status API.

On-demand status example

Replace the placeholders with your environment values. Refer to the API reference for the exact endpoint path and authentication scheme.

curl -X GET \
  "https://{base_url}/{path-to-get-card-issuance-status}?cardId=271b-6e47-8ec3-7f3f" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/json"

PreviousSLA management NextPull and change

Last updated 12 days ago

Was this helpful?