Skip to main content

​
Tokenization

A digital wallet is a device or system for storing digitized versions of payment cards. Examples of digital wallets include Apple Pay and Google Wallet. Digital wallets provide cardholders with a secure and convenient way to store and use their payment cards without needing to carry physical cards. As payment by digital wallet becomes more widely accepted by merchants, the benefit to cardholders increases. Card tokenization is the process of protecting sensitive data by replacing it with secure, surrogate data called a token. To add a payment card to a digital wallet, the card’s sensitive data (that is, the PAN, CVV2, and expiration date) must be replaced with a token that serves as a reference to the card. When a digital wallet accesses a card for payment, it only provides the token, without exposing any of the original card details. The Marqeta platform supports network tokenization, which means that the card network (such as Visa or Mastercard) generates the tokens. The key advantages of supporting payments with digital wallets include:
  • Broad acceptance – Tokenized cards are valid at any merchant that accepts that digital wallet.
  • Increased security – Fewer systems have access to sensitive data, and the card network can implement tight controls and validations. Each network token is exclusive to both a digital wallet and a device (for example, phone and laptop).
For more information, see Digital Wallets and Tokenization.

​
Provisioning methods

Marqeta supports several provisioning methods, which can be enabled or disabled individually so customers can choose the relevant methods they want to allow across their card program. Provisioning methods are outlined below.
  • Manual provisioning – The cardholder initiates the provisioning request by manually entering the data for a new card.
  • In-app provisioning – You integrate to wallet SDKs to allow cardholders to provision cards directly from your mobile application.
  • Card-on-file provisioning – The cardholder initiates the provisioning request by selecting a card that is already on file.

​
Manual provisioning

In the basic provisioning flow, the cardholder initiates the provisioning request either by manually entering the data for a new card or by selecting a card that is already on file (for example, the manual-entry and card-on-file methods). Provisioning occurs through a digital wallet or merchant card on file. It is recommended to enable both manual and card-on-file provisioning to ensure consistent behavior across your program. For more information, see Basic provisioning flow.

​
In-app provisioning

In the instant issuance flow, your mobile application initiates the provisioning request to create a new Marqeta virtual card and then tokenizes it (the in-app-provisioning method). This unique capability from Marqeta allows you to create a virtual card and make it instantly available for use at brick-and-mortar merchants that support the digital wallet and with e-commerce merchants. Google and Apple push provisioning guides are available to assist implementation into Google and Apple SDKs, including server-side implementation guides. Reach out to your Marqeta representative to request accompanying guides. For more information, see Instant issuance flow.

​
Tokenization provisioning flows

For every token activation request, the card network, the Marqeta platform, and the digital wallet 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. There are three types of provisioning flows that can result from a provisioning attempt:
  • 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” — 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.
Note
Apple Pay also uses orange flow, which conforms to the same behavior as yellow flow in the Marqeta platform. Approximately 50% of manual provisioning is yellow flow, and about 2.5% of in-app push provisioning requires additional verification. This does not apply to other digital wallets.
For more information, see Provisioning Digital Wallets Tokens.

​
Marqeta red flow risk rules

If any of the following conditions are met, the token provisioning attempt automatically rejects through the red flow and cardholders are unable to tokenize their card:
  • The PAN, Expiration, and CVV2 do not match any card on file.
  • The card does not exist, is not active, or has expired.
  • The cardholder is not in the ACTIVE state on the Marqeta platform.
  • The number of incorrect CVV2 attempts has exceeded five in the last 24 hours.
  • The wallet device score is 1, indicating a high-risk device (Apple Pay).
  • Token provisioning, or this type of provisioning, is disabled on the Marqeta platform through card product settings.
  • A tokenization risk rule was executed at the network that resulted in a decline.
  • The network was unable to connect to Marqeta.

​
Marqeta yellow flow risk rules

If any of the following conditions are met, the token provisioning attempt automatically goes through the yellow flow via step-up and cardholders are requested to verify themselves before the provisioning attempt is approved:
  • The provisioning attempt is either manual or on-file provisioning, the wallet provider risk reason code does not equal 03, and Apple’s recommendation is yellow (typically ~50% of manual requests).
  • The provisioning attempt is in-app provisioning and the Apple Pay risk code equals 0G, otherwise known as orange flow (typically ~2.5% of Apple Pay in-app requests).
  • A rule was written in the Visa Risk Manager (VRM) tool that recommends to step up this particular request (for instance, if reason code equals 0H, then step up).
  • Marqeta’s customers can optionally choose to enable address verification system (AVS), which compares the address within the provisioning request to the information stored on file. If the address does not match, Marqeta prompts the yellow flow.

​
Token activation request

When the Marqeta platform processes a token activation request, you receive an event notification of type 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, has been 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
    • REQUESTED indicates that token provisioning is still pending.
    • ACTIVE indicates that the token has been provisioned and is active.
    • REQUEST_DECLINED indicates that token provisioning was rejected.
  • digital_wallet_token.fulfillment_status
    • DECISION_GREEN indicates that the token has been provisioned.
    • DECISION_YELLOW indicates that token provisioning is pending and that further action is required to provision the token.
    • DECISION_RED indicates that token provisioning was rejected.
  • 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 further action is required to provision the token.
The token activation request is your key event during token creation. You should ingest all of the information that you require into your system, as this information is not sent again. This event indicates token creation; however, you should wait for the activation transition to be received before the token can be assumed active.
JSON
{
  "type": "token.activation-request",
  "state": "CLEARED",
  "digital_wallet_token": {
    "state": "REQUESTED",
    "fulfillment_status": "DECISION_GREEN",
    "issuer_eligibility_decision": "0000",
    "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": "XXX",
      "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"
    }
  }
}

​
Token lifecycle

After receiving a token activation request, depending on provisioning, the flow within the event determines whether or not and when you get an activation webhook to confirm activation of the digital wallet token. Token lifecycle details are outlined below.
  • Events and their order are depicted by the provisioning flow.
    • In green flow, you typically receive the token activation request and activation transition within a few minutes of each other without any further intervention.
    • For yellow flow, the same two events are sent; however, you receive the activation transition only after successful step-up verification.
    • For red flow, no activation webhook is sent.
  • Once activated, the token can follow a lifecycle similar to that of a card.
    • Once terminated, a token cannot be reactivated.
    • Suspended tokens can be moved back to active.
    • Token state is separate from card state, and tokens continue to work even if a card is not active.
      • Card state only affects provisioning of new tokens (default behavior).
For more information, see Transitioning token states.
JSON
{
  "digitalwallettokentransitions": [
    {
      "token": "bdb97fc3-66bd-4f42-b1f8-3fd25cd0c4d3",
      "digital_wallet_token": {
        "token": "1f20016a-ab69-4dd5-82e8-ee330112c6c2"
      },
      "type": "state.activated",
      "channel": "TOKEN_SERVICE_PROVIDER",
      "state": "ACTIVE",
      "fulfillment_status": "PROVISIONED",
      "reason": "Digital wallet token provisioned to digital wallet",
      "reason_code": "21",
      "created_time": "2021-10-11T19:22:51Z"
    }
  ]
}

​
Step-up verification

When a token activation request results in 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:
  • 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 ACTIVE.
  • Customer service number – Using the Marqeta Dashboard or API, your customer service desk can transition the token to ACTIVE, allowing the token to be used.
For SMS or email OTP to be displayed, they must be configured in the following way:
  • SMS body: Your activation code is 123456 for adding your program card last_four to wallet Pay. This code expires in 30 minutes.
  • Email body: Your activation code is 588997 for adding your program card last_four to wallet Pay. To complete activation, please enter this code when prompted. This code expires in 30 minutes. No one will ever ask you for this code. Do not provide it if asked via phone, email, or chat. If you did not initiate this request, please contact us immediately.
    • Using the same metadata within the cardholder object notification_language, you can select the language of the OTP that is sent to the cardholders.

​
Token transaction

When a cardholder uses a tokenized card to make a payment, Marqeta provides the token details in the transaction payload. This incremental data is provided within the existing transaction webhooks. It is recommended to store all token activation request details and use digital_wallet_token.token to link to the relevant token within your system. The digital_wallet_token field is an optional body where Marqeta has determined a token was used, and it can be associated with all types of transaction webhooks. Token transaction information is provided in both JIT and webhook payloads to allow for authorization decisioning in real time.
JSON
{
  "type": "authorization",
  "state": "PENDING",
  "digital_wallet_token": {
    "token": "33c05aa3-87df-489f-ace5-6b0017113cb3",
    "state": "ACTIVE",
    "state_reason": "Digital wallet token provisioned to digital wallet",
    "fulfillment_status": "PROVISIONED",
    "issuer_eligibility_decision": "0000",
    "created_time": "2021-12-31T17:06:40Z",
    "last_modified_time": "2021-12-31T17:06:46Z",
    "token_service_provider": {
      "token_reference_id": "00000000000",
      "pan_reference_id": "00000000000",
      "correlation_id": "00000000000",
      "token_requestor_id": "50110030273",
      "token_requestor_name": "APPLE_PAY",
      "token_type": "DEVICE_SECURE_ELEMENT",
      "token_pan": "123456______7890",
      "token_expiration": "0125"
    },
    "device": {
      "type": "MOBILE_PHONE",
      "device_id": "00000000000",
      "phone_number": "00000000000",
      "name": "My iPhone",
      "location": "+00.00/-00.00",
      "ip_address": "00.0.000.000"
    },
    "wallet_provider_profile": {
      "account": {
        "id": "00000000000",
        "score": "3"
      },
      "risk_assessment": {
        "score": "DECISION_YELLOW",
        "version": "0001.00"
      },
      "device_score": "3",
      "pan_source": "KEY_ENTERED",
      "reason_code": "02,03,04,0D",
      "recommendation_reasons": ["LOW_ACCOUNT_SCORE"]
    }
  }
}

​
Enabling tokenization

Marqeta provides full access to configure tokenization enablement through the Marqeta Core API. Your card product defines whether tokenization is enabled on the Marqeta platform. The network configuration must be completed before Marqeta receives the messages. Once the network has added your primary account numbers (PANs) to an allow list, testing can begin before launch. Marqeta allows configuration of tokenization to all Marqeta-supported wallets at three different levels:
  • manual_entry – Provisioning attempts from the wallet provider.
  • wallet_provider_card_on_file – Provisioning attempts for the merchant card on file.
  • in_app_provisioning – Provisioning attempts that originate from within the customer app, after card creation to allow auto-provisioning into wallet.
Additionally, you can configure card_art_id at the card product level to define the virtual card art that is displayed within the wallet app. The image asset must be uploaded on the network side, and the identifier can be returned by Marqeta during provisioning.
JSON
{
  "config": {
    "digital_wallet_tokenization": {
      "provisioning_controls": {
        "manual_entry": {
          "enabled": true,
          "address_verification": {
            "validate": false
          }
        },
        "wallet_provider_card_on_file": {
          "enabled": true,
          "address_verification": {
            "validate": false
          }
        },
        "in_app_provisioning": {
          "enabled": true,
          "address_verification": {
            "validate": false
          }
        }
      },
      "card_art_id": ""
    }
  }
}

​
Apple Pay push provisioning triage

During your integration with Apple, issues may occur. This list compiles the most common issues seen during integration, which can assist you in triaging during initial push provisioning. Ninety percent of errors with Apple tokenization projects are due to:
  • Using XCode to test – In this case, the customer must use Test Flight or App Store builds. You must not use XCode or any other development apps. You must either upload to Test Flight or an App Store build for the integration with Marqeta to be tested.
  • Issue with allow lists – This could be that your app is not on an allow list with Apple or you are using a different app to join an allow list (for example, you have added com.marqeta.testapp to an allow list, but Apple is using com.marqeta.testapp.beta).
  • Invalid nonce, nonce signature, or certificate – These could be hardcoded values. However, Marqeta checks the format of this, so it must be in the correct format for a successful response.
  • Marqeta test certificates – Certificates must be full production certificates from Apple.
If you are still encountering issues, reach out to your Apple representative. If you are still in need of assistance, contact your Marqeta representative and share your token reference IDs from Visa and Apple.

​
Tokenization responsibilities

If you have a card program in Europe, there are several responsibilities that you and Marqeta maintain. These responsibilities include:
ResponsibilityPowered ByManaged By
Integrate with the Apple, Google, and Samsung SDKs for push provisioningYouYou
Allow network tokenization from the card networksMarqetaMarqeta
Certify with the Apple Lab prior to Apple launchYouYou
Implement network and wallet risk rulesMarqetaMarqeta
Manage network and wallet relationships in accordance with launch and ongoing supportYouMarqeta
Store and provide webhook information to customers on provisioning and token updatesMarqetaMarqeta

Related topics

Marqeta in Europe OverviewTokenization-as-a-ServiceTransaction Processing in EuropeAbout SCA in EuropeManaging Tokenization Risk