About Digital Wallets
Learn about how digital wallets and tokenized cards work, and how they might be a fit for your card program.
Introduction
What is a digital wallet?
Digital wallets are applications such as Apple Pay and Google Pay that allow your cardholders to securely store their payment information, make payments, and store their payment history.
They can eliminate the need to carry around physical cards by letting your cardholders access their card’s payment information from a smartphone, smartwatch, computer, or tablet. As long as a device supports near field communication (NFC) transmissions, it can be used to make payments.
Because most consumers use wallets on mobile devices, the terms “digital wallet” and “mobile wallet” are often used interchangeably.
How do digital wallets work?
Digital wallets use a special type of card called a tokenized card. From your cardholder's perspective, they function similarly to a virtual or physical card. On the backend, a process called tokenization is used to replace a card's sensitive data (PAN, CVV2, and expiration date) with a token.
When a digital wallet uses a card for payment, it never exposes any of the original card details. Instead, the wallet provides a token. The token can be specific to a particular merchant or wallet, or valid for only a specific number of purchases.
When a payment is made, the merchant sends the token to the card network to match the token with the PAN. The network then forwards the authorization request to Lithic (and you, if you have ASA enabled) to approve or decline the request.
How can cards be added to digital wallets?
There are two primary ways that cards can be added to digital wallets:
- Manual entry: Cardholder either types their card information directly into the digital wallet or uses an embedded image capture feature to scan the front (and sometimes back) of their card
- Push provisioning: Cardholder taps an "add card to digital wallet" button or similar action from your app. Push provisioning makes it easier for cardholders to add your cards to their digital wallets, which means they're more likely to use it when it comes time to pay for a purchase. Implementing push provisioning requires extra steps, as you'll need to integrate your app directly with the wallet provider. See the Push Provisioning page for more information
Implementation Steps
Across digital wallet providers and card networks, there are a few standard steps required to enable your program for digital wallets.
The below steps assume that Lithic is your program manager. Processor only-customers will go through many of the same steps with their program manager's assistance.
Establish a BIN or BIN range
You will first need to work with a bank to establish a BIN or BIN range for your card program, which Lithic can do for you. At this stage, Lithic will work with you to have a project opened with the card network to initiate the process of enabling your cards to be added to digital wallets.
Card art approval
Once you have a BIN in place, you will need to design how your card appears in the digital wallet. You will need to design the front of the card by selecting a card background color and submitting your logo.
Card art must fit within certain specifications and requires approval from the card network, digital wallet provider, and your bank. Here are the specifications that you will need to submit to your Lithic Implementations Manager:
- Company logo in PNG format (1372 x 283 pixels)
- Card design with no rounded corners in PNG format (1536 x 969 pixels)
- Company app icon in PNG format (100 x 100 pixels)
- Hex code value for your card’s background color
- Hex code value for your PAN color
- Hex code value for your card description color
Lithic also enables customers to associate multiple card arts with each BIN. See Flexible Card Art below.
Card configuration
Next, you will need to provide some additional information that will be included alongside your card when your cardholder adds it to a digital wallet app, including:
- Terms and conditions
- Contact information
- Different types of identifiers (which the wallets use to link the card back to your app, where applicable)
Network configuration
After you determine how your card will be configured, the network will take steps to implement your configuration. Your Implementation Manager will submit a request to the network on your behalf to set up your card configuration.
Testing
Once your card and network configuration are complete, you will need to allow-list test cards on your BIN range to ensure that tokens are properly issued when you attempt to add them to digital wallets. This allows you to confirm that cards on your program are working as expected once they're issued to end users.
Submit approvals to network
Next, Lithic will submit forms that document successful testing and certain program details to the card network. While the issuing bank is not explicitly involved in submitting these forms, card networks typically refer to these forms as "financial institution forms".
Apply for approvals from wallet providers
Finally, the card network will take the forms provided in the prior step and submit them to the wallet providers for approval. Each provider may request slightly different information. Once your card receives aprproval from a digital wallet, you are ready to go live. Your cards can now be successfully tokenized and added to the approved wallet.
How Does Tokenization Actually Work?
Digital wallet tokenization involves three parties: the digital wallet (i.e., Apple/Google), the card network, and Lithic.
- First, an end user initiates a digital wallet tokenization either manually (from the wallet app itself) or via push provisioning.
- The wallet then notifies the network (MC or Visa) of the tokenization request, passing along their own recommendation (Decline, Require Additional Authentication, or Approve).
- The network then passes this request to Lithic, who also has the opportunity to make a decision as an issuer. This request comes to Lithic with metadata from both the wallet (Apple/Google) and the network. Lithic offers two ways to decision on digital wallet tokenizations:
- On your behalf, generally on the basis of the wallets’ recommendations.
- Self-serve decisioning with a tokenization decisioning responder, similar to what we allow for normal card transactions with Auth Stream Access. See Tokenization Decisioning.
- Lithic then passes our issuer decision back to the networks, who pass it back to Apple to:
- Green Path (approve tokenization)
- Yellow Path (require additional authentication of the end user)
- Red Path (decline tokenization)
Digital Wallet Cardholder Authentication
During the card tokenization process, the digital wallet and card network may recommend one of three outcomes: approve, require additional authentication, or decline.
If their recommendation is "approve", the tokenization will be approved and the card will be successfully added to the digital wallet. If the recommended outcome is "decline", Lithic will decline the tokenization request. Note: Tokenization Control enables customers to layer their decisions on top of Lithic's and the wallet's recommendation.
If the recommended outcome is "require additional authentication", the cardholder will be prompted (in the digital wallet provider app) to select one of three authentication methods:
- Authenticate via one-time passcode sent via text message or email.
- Authenticate in your mobile application.

Sharing End User Contact Info with Lithic for Digital Wallet Authentication
If the user selects the text or email options, a one-time passcode (OTP) is sent to the user's phone number or email address. Lithic must have this contact info to pass to the wallet to display a preview (e.g., j*[email protected]) to the end user to select their authentication method. There are two ways to share this contact info with Lithic:
- Enrolling accountholders with Lithic. In this case, Lithic will store end users’ accountholder info to be able to deliver an authentication code to their email or phone.
- Using Tokenization Control to pass the end users’ contact info to Lithic (e.g., email/phone) as part of the Tokenization Decisioning Response.
Digital Wallet Authentication via Text or Email
If the user selects the text or email option, a one-time passcode (OTP) is sent to the user's phone number or email address. Either Lithic or you can send the end user this OTP:
- Enterprise customers that choose to have Lithic send the code can customize an email address on their domain from which the OTP will be sent to cardholders. Work with your customer success manager to set up delivery of OTP via Lithic.
- You can also elect to receive a Tokenization Auth Code webhook to send the OTP yourself. Once the cardholder receives their OTP, they'll input it into the digital wallet app to continue the tokenization process.
Digital Wallet Authentication via Mobile Application
You can also enable users to authenticate in your mobile application. When users select this option, the wallet forwards them to your mobile application to complete authentication. To enable mobile app authentication:
- Pass your mobile application name in your Tokenization Decisioning Response to be displayed to the end user in the digital wallet.
- Configure your program in Mastercard Connect or Visa Online with your application identifiers so end users are forwarded to your app from the wallet for authentication.
- Enable your mobile app to call Lithic's /provision endpoint for a payload to pass to the digital wallet for authentication. See Google's App to App verification guide for an overview and reach out to your implementation or customer success manager for Apple's corresponding guide.
To ensure the best possible cardholder experience, Lithic recommends customers use both the update account holder information endpoint and set up Tokenization Decisioning to ensure that Lithic has the right information on file and OTPs are successfully sent to account holders.
Digital Wallet Metadata Event
Each time an an end user attempts to tokenize a card, Lithic will send a webhook to your registered Events webhook URL(s) subscribing to events of type digital_wallet.tokenization_approval_request
with the below payload.
Sample Payload:
{
"event_type": "digital_wallet.tokenization_approval_request",
"created": "String",
"account_token": "String",
"card_token": "String",
"tokenization_source": "String",
"tokenization_token": "String",
"issuer_decision": "APPROVED/VERIFICATION_REQUIRED/DENIED",
"digital_wallet_token_metadata": {
"status": "PENDING",
"token_requestor_id": "String",
"token_requestor_name": "String",
"payment_app_instance_id": "String",
"payment_account_info": {
"payment_account_reference": "String",
"pan_unique_reference": "String",
"token_unique_reference": "String",
"account_holder_data": {
"phone_number": "15555555555"
},
},
},
"wallet_decisioning_info": {
"account_score": "4",
"device_score": "5",
"recommendation_reasons": null,
"recommended_decision": "APPROVED"
},
"device": {
"imei": "String",
"location": "String",
"ip_address": "111.111.111"
},
"customer_tokenization_decision": {
"outcome": "APPROVED",
"response_code": "200",
"latency": "150",
"responder_url": "https://your-responder-url.com",
}
}
event_type | Event type. See Event Types for a full list of events. |
created | An RFC 3339 timestamp for when the card was created. |
account_token | The token of the account under which the tokenization is occurring. |
card_token | The token of the card under which the tokenization is occurring. |
tokenization_source | The source of the tokenization. Possible values are: MANUAL_PROVISION , PUSH_PROVISION , ACCOUNT_ON_FILE , or UNKNOWN . |
tokenization_token | The unique ID of the tokenization attempt. Generated for each tokenization attempt made (i.e., each attempt by a single PAN generates multiple IDs). |
issuer_decision | Lithic's decision on the tokenization. Possible values are: APPROVED , VERIFICATION_REQUIRED , or DENIED . |
Digital Wallet Token Metadata Schema
status | The current status of the tokenization attempt. Possible values are PENDING or DECLINED . |
token_requestor_id | ID representing the party requesting tokenization (this includes merchant tokenizations). |
token_requestor_name | Readable name representing the party requesting tokenization. Possible values are APPLE_PAY , ANDROID_PAY , or SAMSUNG_PAY . |
payment_app_instance_id | ID representing the payment app instance. |
payment_account_reference | Reference for the unique funding PAN; remains the same across tokens derived from that PAN. |
pan_unique_reference | Mastercard-specific PAN reference. |
token_unique_reference | A unique reference used to identify the token for the duration of its lifetime. |
phone number | Phone number associated with the funding account being tokenized. |
Wallet Decisioning Schema
account_score | Score of 1 (poor) to 5 (excellent) given to the Wallet's account to rate their relationship with their customer or account holder. |
device_score | Score of 1 (poor) to 5 (excellent) given to the device by the Wallet Provider to indicate the trustworthiness of the device. |
recommendation_reasons | List of reasons provided to the Wallet Provider on how the recommended decision was reached. If no reasons were provided, value will be null . |
recommended_decision | Recommended decision from the Wallet Provider. Possible values are APPROVED , REQUIRE_ADDITIONAL_AUTHENTICATION , or DECLINED . |
Device Schema
imei | The IMEI number of the device being provisioned. |
storage_technology | The architecture or technology used for token storage. |
location | Latitude and longitude where the device the consumer is attempting to authorize is located. |
ip_address | The IP of the device initiating the request. |
Customer Tokenization Decision
outcome | The outcome from processing the subscribed URL's response to the customer tokenization decision request. Possible values are APPROVED , REQUIRE_ADDITIONAL_AUTHENTICATION , DECLINED , INVALID_RESPONSE , ERROR , or TIMEOUT . |
response_code | Response code returned by the subscribed URL. |
latency | Time taken in milliseconds for the subscribed URL to respond. |
responder_url | The subscribed URL. |
Digital Wallet Tokenization Result Event
Each time a wallet tokenization succeeds or fails, Lithic will send a webhook to your registered Events webhook URL(s) subscribing to events of type digital_wallet.tokenization_result
with the below payload. Note that customer_decision
will take precedence over issuer_decision
if customer_decision
is both present and valid.
Sample Payload:
{
"event_type": "digital_wallet.tokenization_result",
"created": "String",
"account_token": "String",
"card_token": "String",
"tokenization_token": "String",
"tokenization_result_details": {
"customer_decision": "String",
"issuer_decision": "String",
"wallet_decision": "String",
"token_activated_date_time": "String",
"tokenization_decline_reasons": "Array"
}
}
event_type | Event type. See Event Types for a full list of events. |
created | An RFC 3339 timestamp for when the card was created. |
account_token | The token of the account under which the tokenization is occurring. |
card_token | The token of the card under which the tokenization is occurring. |
tokenization_token | The unique ID of the tokenization attempt. Generated for each tokenization attempt made (i.e., each attempt by a single PAN generates multiple IDs). |
Tokenization Result Details
customer_decision | The outcome from processing the subscribed URL's response to the customer tokenization decision request. This value will be null if the customer didn't participate in tokenization decisioning or if decisioning failed.Possible values are APPROVED , REQUIRE_ADDITIONAL_AUTHENTICATION , or DECLINED . |
issuer_decision | Lithic's decision on the tokenization. Possible values are: APPROVED , VERIFICATION_REQUIRED , or DENIED . |
wallet_decision | Recommended decision from the Wallet Provider. Possible values are APPROVED , REQUIRE_ADDITIONAL_AUTHENTICATION , or DECLINED . |
token_activated_date_time | The time of successful tokenization. null if the tokenization was unsuccessful. |
tokenization_decline_reasons | List of reasons the tokenization failed. If the tokenization succeeded, this value will be an empty list [] .Possible reasons are ACCOUNT_SCORE_1 , DEVICE_SCORE_1 , ALL_WALLET_DECLINE_REASONS_PRESENT , WALLET_RECOMMENDED_DECISION_RED , CVC_MISMATCH , CARD_EXPIRY_MONTH_MISMATCH , CARD_EXPIRY_YEAR_MISMATCH , CARD_INVALID_STATE , CUSTOMER_RED_PATH , INVALID_CUSTOMER_RESPONSE , and NETWORK_FAILURE . |
Flexible Card Art
You can associate more than one card art with your BIN. You can then choose which digital wallet card art is displayed when an end user tokenizes their card prior to tokenization. To specify card art for tokenized cards:
- You will need Card Art Approval for each additional card art. Share the new card art you want to associate with your BIN with your implementation or customer success manager. They’ll submit the art to Mastercard and the appropriate sponsor bank for approval. Processor-only customers should submit to Mastercard directly for approval.
- After the card art is approved, your implementations/customer success manager will share a corresponding Card Art Token UUID.
- Append this Card Art Token UUID to
POST
orPATCH
card requests via thedigital_card_art_token
parameter. When the cardholder tokenizes, the digital wallet card art associated with that Card Art Token will be shown in the cardholder's digital wallet.
Please note that Flexible Card Art can only be determined prior to digital wallet tokenization and after tokenization it cannot be changed. New functionality coming by the end of 2023 will allow customers to update the digital card art dynamically, even after tokenization is complete.
Updated 5 months ago