Card tokenization flow and events

Credit card tokenization converts sensitive cardholder data to a randomly-generated string of numbers called a token that can be used in payments or other financial transactions. Similar to encryption, tokenization obfuscates the original data to render it unreadable during a digital transmission breach or other exposure.

A tokenized card, stored in a digital wallet, is known as a card on file. The most significant impact you, as an issuer, can have during the tokenization process is to provide an anti-fraud webhook. To create a card on file in a Pismo digital wallet, call the Create card on file endpoint. All other requests for tokenization come from the network to Pismo.

The network communication to Pismo during tokenization involves five basic operations. Depending on network (Visa, Mastercard), they may vary slightly, but they are roughly the same.

  1. Eligibility - The token requestor, such as Samsung Pay or Android Pay, checks if a card can be digitized according to configurations the issuer previously made with the network.

  2. Authentication - The card is ready to be digitized and the authentication process begins. There are three different results depending on eligibility:

    • Approved - The card is digitized, skipping the anti-fraud check. This is the expected outcome.

    • Conditional - The card is digitized after a confirmation method - such as SMS or email challenge - is successful. This is known as ID&V (Identity and Verification).

    • Not approved - The card is not digitized and the denial reason is sent to the issuer.

  3. OTP - In the conditional flow, Pismo sends a challenge to cardholder to confirm identity. This is known as OTP (One-Time Passcode).

  4. Token activated - Once approved, the token is activated.

  5. Token update - 3rd-party entities (network, cardholder, etc.) notify Pismo of any token changes, such as a change in status.

The table below shows the operations and how the two main networks refer to them:

Token operationMastercard (MDES)Visa (VTS)
EligibilityTECheck eligibility
AuthenticationTAApprove provisioning and get cardholder verification method (CVM)
OTPACSend passcode
Token activatedTCToken create notification
Update notificationTVToken notification

Tokenization events

The following are examples of events that occur during the card tokenization process. Except where noted, all of these are notification-1 event examples.

For information on setting up event notifications, see the Data and reporting overview .

For information on interpreting event data from the network, refer to the VISA Token Service (VTS) Issuer API Specifications (JSON) manual or the Mastercard Customer Interface Specification manual.

Mastercard Digital Enablement Service (MDES)

MDES token authorization (TA) provisioning

Important fields:

  • network_data.de48_additional_data_private_user.se26_wallet_program_data.sf1_wallet_identifier

    Wallet identifier:
    103 = apple pay
    216 = google pay
    217 = samsung pay
    327 = merchant tokenization program

  • network_data.de124_member_defined_data.mdes_data.token_authorization.sf2_primary_account_number_source

    PAN source identifier:
    1 = Card on file
    2 = Card added manually
    3 = Card added via application

MDES TA example event

MDES activation code (AC)

The AC message brings a code from the network which we have to reply back to the user.

Event occurs if the user chooses the challenges OTPSMS or OTPEMAIL. If the user chooses other challenge methods (app-to-app OTPAPP, call center OTPCALL) the process takes place between the app/call center and the network.

Important fields

  • network_data.de124_member_defined_data.mdes_data.activation_code.sf2_activation_code

    Activation code that should be sent to the cardholder.

  • network_data.de124_member_defined_data.mdes_data.activation_code.sf3_activation_code_expiration_date_time

    Activation code expiration datetime

  • network_data.de124_member_defined_data.mdes_data.activation_code.sf4_consumer_activation_pref_method

    Authentication method choose by cardholder:
    1 - otp SMS
    2 - otp E-MAIL
    3 - otp Call center
    6 - otp APP to APP

MDES AC example event

MDES tokenization complete (TC)

Indicates the network has provisioned the token. This is when the token becomes active and can be used in a tokenized transaction

Important fields

  • network_data.de124_member_defined_data.mdes_data.tokenization_complete.sf2_number_of_active_tokens

    Identify total activated tokens

  • network_data.de124_member_defined_data.mdes_data.tokenization_complete.sf4_device_name

    Device name

MDES TC example event

MDES TV (tokenization event)

Token lifecycle messages, such as token status changes. The network can send, for example, a token cancellation of a token.

Important fields

  • network_data.de124_member_defined_data.mdes_data.tokenization_event_notification.sf2_event_indicator

    Lifecycle event type:
    3 = Deleted token
    4 = Deleted from consumer device
    7 = Resumed token
    9 = Token replaced

  • network_data.de124_member_defined_data.mdes_data.tokenization_event_notification.sf4_event_requestor

    Agent that started the tokenization provisioning:
    0 = Wallet
    1 = Funding account
    2 = Cardholder
    3 = Systematically

MDES TV example event

MDES TE refusal

Event: notification_refusal-1

Important fields

MDES TE refusal example event

Visa Token Service (VTS)

VTS approve provisioning

Important fields

  • deviceInfo.deviceBrand

    Identify device’s brand

  • panSource

    Identify PAN source

VTS approve example event

VTS get cardholder verification method (CVM)

VTS get CVM example event

VTS passcode verification

Important fields

  • otpValue

    One time passcode value

  • otpMethodIdentifier

    One time passcode method:

        kdaufuf783jnch = otpSMS
        kda74290fjfn84 = otpEmail
        jjfa8f7jnfyfgg = otp App to App
        kfa87fjrnnyuvy = otp call center
VTS passcode example event

VTS token deactivated

VTS token deactivated example event

VTS token suspended

VTS token suspended example event

VTS token resume

VTS token resume example event