Managing the Lifecycle of Digital Wallet Tokens
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
Copy section link
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:
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_YELLOWand none designates
DECISION_RED, the token is placed in a pending state and further action is required.
DECISION_YELLOWindicates 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 their own business logic to determine the level of risk associated with creating a new token.
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
Copy section link
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 – The Marqeta platform sends a verification passcode to the cardholder using email or SMS; the cardholder enters the passcode into the digital wallet for identity verification. The Marqeta platform transitions the digital wallet token to
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. This verification method cannot be used concurrently with the Access code in authorization message method.
Access code in authorization message – The card network generates an access code, then posts a small authorization transaction to the cardholder’s account that includes the access code in the
card_acceptorfield. The cardholder logs in to their online banking application to retrieve the code. The cardholder enters the access code into the digital wallet for identity verification. The Marqeta platform transitions the digital wallet token to
ACTIVE. This verification method cannot be used concurrently with the Over-the-phone verification method.
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 who made that decision).
To process requests that require further verification:
Ensure that your webhook endpoint is configured to receive notifications for
token.activation-requesttype events. These notifications contain the entire token activation request. (See Webhooks Management for more information on configuring your webhook endpoint. See Transactions for more information about fields contained in the token request.)
POSTrequest to the
/digitalwallettokentransitionsendpoint and set the state based on your decision. For example, if you want to approve the request, set the
ACTIVE. (See Digital Wallets Management for more information on the fields to use when processing a token activation request with the
Determining the status of a token request
Copy section link
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
ACTIVEindicates that the token has been provisioned and is active.
REQUESTEDindicates that token provisioning is still pending.
REQUEST_DECLINEDindicates that token provisioning was rejected.
DECISION_GREENindicates that the token has been provisioned.
REJECTEDindicates that token provisioning was rejected (
DECISION_YELLOWindicates that token provisioning is pending and that further action is required to provision the token.
0000indicates that the token has been provisioned.
token.activation.verification.requiredindicates 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:
Transitioning token states
Copy section link
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.
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.
The digital wallet token is permanently non-functional.
This state results from the digital wallet, the card network, or the Marqeta platform designating
The digital wallet token is provisioned and functional.
A digital wallet token can transition to an
The digital wallet token is temporarily non-functional.
A token can transition from
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 for more information about these notifications.