Synchronizing Digital Wallet Tokens with Card State

Hidden When a card is transitioned through the Marqeta platform, any associated digital wallet tokens (DWTs) will remain unchanged by default. The underlying DWT will continue to be used until the cardholder receives a replacement card, allowing for continued spending until the new card arrives. In some circumstances, you might need to suspend or terminate the card and all associated DWTs. Previously, such actions would have required you to transition the card, along with each individual DWT. However, the Marqeta platform allows you to synchronize the card state with all of its associated DWTs. A decision to sync with the card state can be made when moving the card state in a call made to the /cardtransition endpoint. You can set sync_state_with_dwts to true to synchronize the state of the card with the state of its associated DWTs, which must be valid when performing the given transition. For example, if the card is transitioning to the SUSPENDED state, then only the DWTs with ACTIVE tokens will be synchronized as part of the state transition.

JSON

{
  "card_token": "39bb022d-8e48-446f-9d81-1c6ea4e37a4d",
  "channel": "API",
  "state": "SUSPENDED",
  "sync_state_with_dwts": true
}

Webhooks

You will receive the same webhooks for digital wallet transitions as for standard card transitions, along with several additional values in existing fields.

Transitioning cards

The following code sample shows the additional values in a sample webhook that will appear when transitioning the card state.

JSON

{
  "cards":
  [
    {
      "token": "6f362bd6-0f63-4c7a-9630-004fd7a55308",
      "card_token": "39bb022d-8e48-446f-9d81-1c6ea4e37a4d",
      "user_token": "12237f64-2a08-4906-9ec1-55f8a97a2084",
      "state": "SUSPENDED",
      "reason": "Suspended card",
      "reason_code": "14",
      "channel": "API",
      "fulfillment_status": "ISSUED",
      "validations":
      {
        "user":
        {
          "birth_date": false,
          "phone": false,
          "ssn": false,
          "random_name_line1_postfix": false
        }
      },
      "type": "state.suspended",
      "created_time": "2023-02-02T22:22:36Z",
      "card_product_token": "1f153e78-f3ec-45b2-a7ca-b39075038568",
      "last_four": "1295",
      "pan": "5391MASKED1295",
      "expiration": "0925",
      "expiration_time": "2025-09-30T23:59:59.000Z",
      "barcode": "27202965166738342604",
      "pin_is_set": false,
      "user":
      {
        "metadata":
        {}
      },
      "card":
      {
        "metadata":
        {}
      }
    }
  ]
}

Transitioning DWTs

DWT transitions do not require you to ingest any new fields. However, the reason field will contain the value of SYNC_CARD_STATE during transitioning. This value informs you that Marqeta has automatically transferred the token.

JSON

{
  "digitalwallettokentransitions":
  [
    {
      "token": "d6767076-bf44-4f9d-b034-ff4fca3800b6",
      "digital_wallet_token":
      {
        "token": "65063a17-cd98-4551-8ce5-248ab380fccd"
      },
      "type": "state.suspended",
      "channel": "API",
      "state": "SUSPENDED",
      "fulfillment_status": "PROVISIONED",
      "reason": "SYNC_CARD_STATE",
      "reason_code": "01",
      "created_time": "2023-02-02T22:22:38Z"
    }
  ]
}

Guides

​Webhooks

​Transitioning cards

​Transitioning DWTs

Webhooks

Transitioning cards

Transitioning DWTs