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.

High-level flow of physical card production and shipment events.

How it works

Use one or both approaches:

Notifications (recommended)

• 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.

On-demand

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

Recommended integration

1

Persist status per card

Store the latest known details.status for each cardId.

2

Process notifications first

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

3

Reconcile on demand when needed

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

4

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 transition diagram for physical card issuance.

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

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": "CARD_PROD_REQUESTED"
      }
    }
  ]
}

DATA_PREPARED

{
  "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"
      }
    }
  ]
}

DATA_EXCEPTION

{
  "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"
    }
  ]
}

CARD_SHIPPED

{
  "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"
        }
      }
    }
  ]
}

CARD_SHIPPED with tracking

{
  "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.

Status transitions including exceptions and on-hold states.

Operational view of issuance steps and state changes.

Sequence diagram for notifications and status changes during physical card issuance.

Physical card issuance tracking on demand

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

High-level flow of physical card production and shipment events.

On-demand status example

Request

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"