> ## Documentation Index > Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Managing the Digital Wallet Token Lifecycle > Learn how to manage all phases of the digital wallet token lifecycle from provisioning to termination. For every token activation request, the card network, the Marqeta platform, and the digital wallet individually assess the legitimacy of the request and reach an approval decision. After this initial determination is made, you can process requests that require further verification. Additionally, you can transition a digital wallet token to any valid state at any time during its lifecycle.

Token approval process

Before you can insert a card into a digital wallet, the card network must provision a token to replace the card's sensitive data. During token provisioning, the digital wallet, the card network, and the Marqeta platform (the issuer processor) each perform identification and verification (ID\&V) steps to individually assess the legitimacy of the token provisioning request. Each participant scores the request by tagging it with one of the following colors: | Color | Action | Description | | ------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Red | Do not provision | If any participant designates `DECISION_RED`, the token is not provisioned and the cardholder is informed that the tokenization request failed. | | Green | Provision | If all participants designate `DECISION_GREEN`, the token is immediately provisioned. | | Yellow | Further verification | If any participant designates `DECISION_YELLOW` and none designates `DECISION_RED`, the token is placed in a pending state and further action is required. `DECISION_YELLOW` indicates that the participant is unsure of the risk associated with provisioning the token. | After the card network, the Marqeta platform, and the digital wallet reach an approval decision for the token activation request, the Marqeta platform sends an event notification to your webhook endpoint. If the token activation request results in a `DECISION_YELLOW`, you can perform further verification and transition the token to the appropriate state. Each participant in the tokenization process uses its own business logic to determine the level of risk associated with creating a new token. A `DECISION_YELLOW` usually originates at the digital wallet provider and is invoked due to issues such as "Account not in good standing" or "Suspected fraud."

Processing requests that require further verification

When a token activation request results in a `DECISION_YELLOW`, you must take additional steps to verify the legitimacy of the request. You must provide at least two methods of verification for your users. Available methods of verification include the following: * **In-app verification** – Your app verifies the cardholder's identity using your own business logic. You make an API call to transition the digital wallet token based on the verification decision you reach. * **One-time passcode via email** – The Marqeta platform sends a verification passcode to the cardholder by email. The cardholder enters the passcode into the digital wallet for identity verification. The Marqeta platform transitions the digital wallet token to `ACTIVE`. * **One-time passcode via SMS** – The Marqeta platform sends a verification passcode to the cardholder by SMS. The cardholder enters the passcode into the digital wallet for identity verification. The Marqeta platform transitions the digital wallet token to `ACTIVE`. * **Over-the-phone verification** – The cardholder calls in to your call center or interactive voice response (IVR) system, which verifies their identity. You make an API call to transition the digital wallet token, based on the verification decision you reach. Contact your Marqeta representative to configure these options. If you are using over-the-phone or in-app verification, you must assess the legitimacy of the request. Depending on the outcome of your assessment, you can explicitly activate or terminate the token request, effectively overriding the `DECISION_YELLOW` (regardless of which participant made that decision). To process requests that require further verification: Ensure that your webhook endpoint is configured to receive notifications for `token.activation-request` type events. These notifications contain the entire token activation request. See [Webhooks](/core-api/webhooks/) for more information on configuring your webhook endpoint. See also [Transactions](/core-api/transactions/) for more information about fields contained in the token request. Send a `POST` request to the `/digitalwallettokentransitions` endpoint and set the state based on your decision. For example, if you want to approve the request, set the `state` field to `ACTIVE`. See [Digital Wallets Management](/core-api/digital-wallets-management/) for more information on the fields to use when processing a token activation request with the `/digitalwallettokentransitions` endpoint. ```json JSON lines wrap theme={null} { "token": "my_transition_04", "reason_code": "00", "digital_wallet_token": { "token": "b98cb680-2fd4-4c14-aa56-8d05091209d5" }, "state": "ACTIVE", "reason": "Passed additional identity verification" } ```

Determining the status of a token request

If you have properly configured your webhook endpoint, you will receive an event notification of type `token.activation-request` whenever the Marqeta platform processes a token activation request. This event notification contains the response to the token activation request, which allows you to determine the approval decision and whether the token has been provisioned, rejected, or is pending. To determine the status of a token activation request, monitor these fields in the `token.activation-request` notification: * **digital\_wallet\_token.state** * `ACTIVE` indicates that the token has been provisioned and is active. * `REQUESTED` indicates that token provisioning is still pending. * `REQUEST_DECLINED` indicates that token provisioning was rejected. * **digital\_wallet\_token.fulfillment\_status** * `DECISION_GREEN` indicates that the token has been provisioned. * `REJECTED` indicates that token provisioning was rejected (`DECISION_RED`). * `DECISION_YELLOW` indicates that token provisioning is pending and that further action is required to provision the token. * **digital\_wallet\_token.issuer\_eligibility\_decision** * `0000` indicates that the token has been provisioned. * `token.activation.verification.required` indicates that token provisioning is pending and that further action is required to provision the token. The following code sample shows a `token.activation-request` event notification: ```json JSON expandable lines wrap theme={null} { "type": "token.activation-request", "state": "CLEARED", "token": "23843", "user_token": "d5e46927-0c84-4010-af80-5844fce8c154", "acting_user_token": "d5e46927-0c84-4010-af80-5844fce8c154", "card_token": "348b7e88-f689-4a72-b4ed-20a178d5919a", "gpa": { "currency_code": "USD", "ledger_balance": 10, "available_balance": 0, "credit_balance": 0, "pending_credits": 10, "balances": { "USD": { "currency_code": "USD", "ledger_balance": 10, "available_balance": 0, "credit_balance": 0, "pending_credits": 10 } } }, "duration": 50, "created_time": "2020-07-16T17:41:41Z", "user_transaction_time": "2020-07-16T17:41:41Z", "settlement_date": "2020-07-16T00:00:00Z", "amount": 0, "issuer_interchange_amount": 0, "approval_code": "766530", "response": { "code": "0000", "memo": "Approved or completed successfully" }, "network": "VISA", "subnetwork": "VISANET", "acquirer_fee_amount": 0, "acquirer": { "institution_country": "840", "institution_id_code": "871606746", "retrieval_reference_number": "936048123849", "system_trace_audit_number": "468607" }, "digital_wallet_token": { "token": "d7eed4f0-d61b-441d-879b-e7102acc23f4", "card_token": "348b7e88-f689-4a72-b4ed-20a178d5919a", "state": "REQUESTED", "fulfillment_status": "DECISION_GREEN", "issuer_eligibility_decision": "0000", "created_time": "2020-07-16T17:41:41Z", "last_modified_time": "2020-07-16T17:41:41Z", "token_service_provider": { "token_reference_id": "408564928506142", "pan_reference_id": "41673069", "token_requestor_id": "28270789220", "token_requestor_name": "UNKNOWN", "token_type": "DEVICE_SECURE_ELEMENT", "token_score": "99", "token_assurance_level": "00", "token_eligibility_decision": "DECISION_GREEN" }, "device": { "type": "MOBILE_PHONE", "language_code": "ne", "device_id": "742968498356601664707181916878546216842668795786", "phone_number": "5557994077", "name": "ramps", "location": "70.558807589/67.436713420", "ip_address": "169.10.148.247" }, "wallet_provider_profile": { "account": { "id": "577804066", "email_address": "username@gmail.com", "score": "5" }, "risk_assessment": { "score": "DECISION_GREEN", "version": "10" }, "device_score": "5", "pan_source": "KEY_ENTERED", "reason_code": "01020304" }, "address_verification": { "name": "", "street_address": "nil", "postal_code": "nil" } }, "user": { "metadata": {} }, "card": { "metadata": {} }, "address_verification": { "request": { "street_address": "nil", "postal_code": "nil" }, "on_file": { "street_address": "", "postal_code": "" }, "response": { "code": "0303", "memo": "Not validated" } }, "card_security_code_verification": { "type": "CVV2", "response": { "code": "0000", "memo": "Card security code match" } }, "fraud": { "network": { "transaction_risk_score": 57, "account_risk_score": 8 } }, "card_acceptor": { "mid": "000090197809064", "mcc": "6411", "name": "Marqeta Storefront", "street_address": "111 Main St", "city": "St. Petersburg", "country_code": "USA" }, "pos": { "pan_entry_mode": "MAG_STRIPE", "pin_entry_mode": "TRUE", "terminal_id": "TR100000", "terminal_attendance": "ATTENDED", "card_holder_presence": false, "card_presence": false, "partial_approval_capable": false, "purchase_amount_only": false }, "transaction_metadata": { "payment_channel": "OTHER" } } ``` For more information on the fields returned by a `token.activation-request` event notification, see the [Transactions](/core-api/transactions/) API reference page. For more information about updating the state of the digital wallet token, see the [Digital Wallets Management](/core-api/digital-wallets-management/) API reference page.

Transitioning token states

You can transition a token to any valid state by issuing a `POST` request to the `/digitalwallettokentransitions` endpoint. The following table describes the available states and transitions. | Value | Description | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | REQUESTED | The digital wallet token has been created but not yet provisioned and is non-functional. This is the initial state of a digital wallet token. | | REQUEST\_DECLINED | The digital wallet token is permanently non-functional. This state results from the digital wallet, the card network, or the Marqeta platform designating `DECISION_RED`. | | ACTIVE | The digital wallet token is provisioned and functional. A digital wallet token can transition to an `ACTIVE` state only from a `REQUESTED` or `SUSPENDED` state. | | SUSPENDED | The digital wallet token is temporarily non-functional. A token can transition from `ACTIVE` to `SUSPENDED` and back to `ACTIVE` again. Tokens can be suspended by the fraud system, issuer, customer, or cardholder. | | TERMINATED | The digital wallet token is permanently non-functional and cannot transition to any other state. Tokens can be terminated by the issuer, customer, or cardholder. | A webhook event notification alerts you whenever a token transitions state. See [Digital Wallet Token Transition Events](/core-api/event-types/#_digital_wallet_token_transition_events) for more information about these notifications. **Note** Any number of tokens can be generated for the same card. However, the state of each token is independent from any other token and from the card. For example, terminating token A has no effect on token B, even if they both represent the same card. Similarly, terminating the card has no effect on tokens A or B. For more information, see [Managing Lost, Stolen, or Damaged Cards](/developer-guides/managing-lost-stolen-or-damaged-cards/). Digital wallet token lifecycle

Synchronizing digital wallet tokens with card state

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. Now, 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 JSON lines wrap theme={null} { "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 JSON expandable lines wrap theme={null} { "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": "2024-02-02T22:22:36Z", "card_product_token": "1f153e78-f3ec-45b2-a7ca-b39075038568", "last_four": "1295", "pan": "5391MASKED1295", "expiration": "0925", "expiration_time": "2026-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 may contain the following values during transitioning: | Value | Description | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `SYNC_CARD_STATE` | Indicates that Marqeta has automatically transferred the token. | | `Out of date credential - expired PAN` | (*Visa only*) Indicates that Marqeta has automatically terminated the token because the associated PAN credentials are expired. This value appears in the `reason` field of the `digitalwallettokentransition.terminated` webhook payload. | ```json JSON lines wrap theme={null} { "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": "2024-02-02T22:22:38Z" } ] } ``` ## Related topics - [Provisioning Digital Wallet Tokens](/docs/developer-guides/provisioning-digital-wallet-tokens.md) - [Digital Wallets Overview](/docs/developer-guides/digital-wallets-landing-page.md) - [Managing Lost, Stolen, or Damaged Cards](/docs/developer-guides/managing-lost-stolen-or-damaged-cards.md) - [Digital Wallets Management](/docs/core-api/digital-wallets-management.md) - [Digital Wallets and Tokenization](/docs/developer-guides/digital-wallets-and-tokenization.md)