# Issuer-Initiated Tokenization
source: https://developer.mastercard.com/mdes-pre-digitization/documentation/use_case/issuer-tokenization/index.md
* [How it works](https://developer.mastercard.com/mdes-pre-digitization/documentation/use_case/issuer-tokenization/index.md#how-it-works)
* [Implementation](https://developer.mastercard.com/mdes-pre-digitization/documentation/use_case/issuer-tokenization/index.md#implementation)
* [Reference API Implementation](https://developer.mastercard.com/mdes-pre-digitization/documentation/use_case/issuer-tokenization/index.md#reference-api-implementation)
* [Encryption of Card Information](https://developer.mastercard.com/mdes-pre-digitization/documentation/use_case/issuer-tokenization/index.md#encryption-of-card-information)
* [Requesting the Mastercard Encryption Public Key](https://developer.mastercard.com/mdes-pre-digitization/documentation/use_case/issuer-tokenization/index.md#requesting-the-mastercard-encryption-public-key)
* [Encrypting the Ephemeral AES Key](https://developer.mastercard.com/mdes-pre-digitization/documentation/use_case/issuer-tokenization/index.md#encrypting-the-ephemeral-aes-key)
* [TAV Creation](https://developer.mastercard.com/mdes-pre-digitization/documentation/use_case/issuer-tokenization/index.md#tav-creation)
Issuer-initiated digitization allows account holders to push payment details to participating merchants, digital wallets and commerce platforms for secure, convenient checkouts anywhere and any way they choose to pay. It eliminates the need for a cardholder to enter card details in the wallet.
MDES provides two different methods to push tokenized card to a digital wallet or a participating merchant:
* Using [Token Connect and Control](https://developer.mastercard.com/mdes-token-connect/documentation/use-cases/)
* Using the traditional TAV method as explained below:
Cardholder accesses the issuer's mobile banking app to check their account balance. They see a new service that allows them to load their payment cards into a digital wallet. The cardholder likes the convenience of making online and in-app purchases using their mobile phone. They also use a digital wallet on their mobile phone to make contactless payments in stores. As a result, they have decided to opt into the new service and load their card into the digital wallet. This way, they can shop with confidence, knowing that their purchases are both convenient and secure.
##### High-Level User Experience for Issuer App-Initiated Digitization
## How it works {#how-it-works}
Wallet Providers define the proprietary APIs to be used by an issuer app or an issuer's server to push digitization. MDES can process the following data:
* Encrypted card information (required)
* Tokenization Authentication Value (TAV) is highly recommended for all wallets except Apple Pay and Google where it is mandatory
For wallet providers other than Apple Pay, the issuer-initiated digitization data is intended to be passed through to MDES with the encrypted card information and TAV unchanged by the wallet provider.
Note: The pass-through mechanism described in this guide does not apply to Apple Pay; refer to the Apple Pay wallet API documentation.
The Wallet Provider should also include the following data within their APIs:
* **Network identifier** - Enables the wallet to identify which brand is associated with the request (note that the encryption of the sensitive financial account information described in this document is only relevant to the Mastercard brand)
* **Last four digits of the Account PAN** - Enables the wallet provider to display this with the token so that a cardholder can see the token is linked to their card
During the typical digitization workflow for wallet providers:
1. MDES returns the issuer's Terms and Conditions to the wallet provider.
2. The wallet provider then presents these to the cardholder for acceptance before proceeding with digitization.
Depending on the design, the Terms and Conditions may be presented either by:
* The wallet app itself on the wallet app's user interface.
* The wallet app may pass the Terms and Conditions back to the issuer app to be displayed on the issuer app's user interface.
Tip: It is recommended that the complete issuer-initiated digitization data is passed to the wallet provider. Also, it should be passed such that it can be considered a single blob of data that will not be affected by any specific API mechanism used by the app or server APIs. Additional data fields can be passed over the API using the format determined by the wallet provider.
## Implementation {#implementation}
A wallet provider should implement asynchronous APIs to initiate the digitization processes, and therefore, provide a call-back mechanism. This is so that the issuer app may be informed of the result of the digitization processes.
Following digitization, a wallet provider may return some or all of the following data to the issuer app or issuer server:
* **Indication of success or failure** - The reasons for failure are many and varied, so a wallet provider should consider which failures are appropriate to report to an issuer. Only situations that would allow an issuer to resolve a failure should be reported in detail so that the issuer can take necessary corrective measures.
* **Last four digits of the token** - An issuer may want to display the last four digits of the token associated with a transaction, to provide a more complete statement facility.
* **Token Expiration Date** - An issuer may want to display the expiration date of the token, which will be different from that of the digitized card, within their issuer app.
* **Token Unique Reference** - This value allows an issuer to perform lifecycle management activities using the MDES Customer Service API. Providing the value to the issuer app may simplify consumer-driven lifecycle activities if deployed within the issuer app and would, for example, permit the cardholder to delete a wallet token from within the issuer app.
* **Payment Application Instance ID** - This value can assist the issuer in determining which device the card has been digitized to.
##### Example of an Issuer App-Initiated Digitization Sequence
## Reference API Implementation {#reference-api-implementation}
Note: The field names stated here are examples of the field names that a proprietary App-to-App API could have.
The `IssuerInitiatedDigitizationData` object is a base64-encoded JSON structure containing the following fields:
| Suggested Object Name | Suggested Object Contents | Usage |
|---------------------------------|---------------------------------|------------------------------------------------------------------------------------------------------------------------|
| IssuerInitiatedDigitizationData | cardInfo | Should only contain card data. Should not be provided if fundingAccountInfo is present. |
| | fundingAccountInfo | Can contain card data or non-card based payments. Should not be provided if `cardinfo` is present. |
| | tokenizationAuthenticationValue | (string, max length 2048), which is cryptographically-signed by the issuer to pre-authorize this digitization request. |
* The `fundingAccountInfo` field supersedes the `cardInfo` field for supplying encrypted card data. The introduction of the `FundingAccountInfo` object is to prepare Mastercard for future opportunities to support non-card-based payments. Customers will be informed of the details when such funding account use cases are implemented.
* The issuer and wallet performing the issuer-initiated digitization must either use `cardInfo` or both use `fundingAccountInfo`.
* The data structure must persist when the wallet is passing the information through to Mastercard.
* Issuers must follow the wallet's guidelines on support of the `CardInfo` object, the `FundingAccountInfo` object or both, and on any migration plan from the `CardInfo` object to the `FundingAccountInfo` object defined for the wallet.
Note: The object used to provide a wallet with encrypted card information in an issuer-initiated digitization flow can differ from the object the issuer chooses to receive in pre-digitization messages. For example, an issuer can provide a wallet with the `CardInfo` object while being configured to receive the `FundingAccountInfo` object in Pre-Digitization API messages.
The `FundingAccountInfo` object is a JSON structure containing the following fields.
| Field and Description | Data Type | Max Length | Required? |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------|------------|-------------|
| **panUniqueReference** For repeat digitizations (when the issuer supports it), the unique reference allocated to the financial account will be used to retrieve the financial account information. When supplied, the account information is omitted from FundingAccountData. Only allowed if tokenUniqueReference is not present and encrypted data does not contain the account information. | String | 64 | Conditional |
| **tokenUniqueReference** A unique reference assigned following the allocation of a token used to identify the token for the duration of its lifetime. For repeat digitizations (when the issuer supports it), the unique reference allocated to the token will be used to retrieve the financial account information. When supplied, the account information is omitted from FundingAccountData. | String | 64 | Conditional |
| **encryptedPayload** Contains an encrypted FundingAccountData object. Required if panUniqueReference and tokenUniqueReference are not present. | String Hex-encoded data (case-insensitive). | N/A | Conditional |
The `EncryptedPayload` object is a JSON structure containing the following fields.
| Field and Description | Data Type | Max Length | Required? |
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------|------------|-----------|
| **publicKeyFingerprint** The fingerprint of the Mastercard public key used to encrypt the ephemeral AES key. | String. Hex-encoded data (case-insensitive). | 64 | Yes |
| **encryptedKey** One-time use AES key encrypted by the Mastercard public key (as identified by 'publicKeyFingerprint') using the OAEP or RSA Encryption Standard PKCS #1 v1.5 (depending on the value of 'oaepHashingAlgorithm'. As this AES key is encrypted using Mastercard's public key; only Mastercard can decrypt it. The requirement is for a 128-bit key (with a 256-bit key supported as an option). | String. Hex-encoded data (case-insensitive). | 512 | Yes |
| **oaepHashingAlgorithm** Hashing algorithm used with the OAEP scheme. If omitted, then the RSA Encryption Standard PKCS #1 v1.5 will be used. Must be one of: * SHA256 = Use the SHA-256 algorithm * SHA512 = Use the SHA-512 algorithm | String | 6 | No |
| **iv** The initialization vector used when encrypting data using the one-time use AES key. Must be exactly 16 bytes (32 character hex string) to match the block size. If not present, an IV of zero is assumed. | String. Hex-encoded data (case-insensitive). | 32 (exact) | No |
| **encryptedData** Contains the encrypted FundingAccountData JSON object. Encrypted by the ephemeral AES key using CBC mode (IV as provided in 'iv', or zero if none is provided) and PKCS#7 padding. The JSON object being encrypted will be defined in the context of the API call. | String. Hex-encoded data (case-insensitive). | 256 K | Yes |
The `FundingAccountData` object is a JSON structure containing the following fields.
| Field and Description | Data Type | Max Length | Required? |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------|------------|-------------|
| **cardAccountData** The credit or debit card information for the account that is being tokenized. Required if `financialAccountData` is not present unless a valid panUniqueReference or tokenUniqueReference was given in FundingAccountInfo. | CardAccountData | N/A | Conditional |
| **financialAccountData** The financial account information for non-card based payment that is being tokenized. This could be a bank account or other type of financial account. Required if cardAccountData is not present unless a valid panUniqueReference or tokenUniqueReference was given in FundingAccountInfo. | FinancialAccountData | N/A | Conditional |
| **accountHolderData** Additional information that can be used to identify the account holder, such as name and address. | AccountHolderData | N/A | No |
| **source** The source of the account information. Must be one of: * ACCOUNT_ON_FILE = Source was an existing account on file * ACCOUNT_ADDED_MANUALLY = Source was new account entered manually by the account holder * ACCOUNT_ADDED_VIA_APPLICATION = Source was new account added by another application (for example, Issuer banking app) | String | 32 | Yes |
| **dataValidUntilTimestamp** The date/time after which this encrypted object is considered invalid. If present, all systems must reject this encrypted object after this time and treat it as invalid data. Must be expressed in ISO 8601 extended format as one of the following, where \[.sss\] is optional and can be 1--3 digits: * YYYY-MM-DDThh:mm:ss\[.sss\]Z * YYYY-MM-DDThh:mm:ss\[.sss\]±hh:mm
Must be a value no more than 30 days in the future. Mastercard recommends using a value of Current Time + 30 minutes. | String | 29 | No |
The `CardAccountData` object is a JSON structure containing the following fields.
| Field and Description | Data Type | Max Length | Required? |
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|-------------------|-------------|
| **accountNumber** The Account Primary Account Number of the card to be digitized. Required unless a valid panUniqueReference or tokenUniqueReference was given in FundingAccountInfo. | String (numeric) | 19 (min length 9) | Conditional |
| **expiryMonth** The month of the expiration date of the card to be digitized. Note that the expiry date may not be in the past. May be omitted if the card does not have an expiry date. Required unless a valid panUniqueReference or tokenUniqueReference was given in FundingAccountInfo. | String (numeric) | 2 (exact) | Conditional |
| **expiryYear** The year of the expiration date of the card to be digitized. Note that the expiry date may not be in the past. May be omitted if the card does not have an expiry date. Required unless a valid panUniqueReference or tokenUniqueReference was given in FundingAccountInfo. | String (numeric) | 2 (exact) | Conditional |
The `FinancialAccountData` object is a JSON structure containing the following fields.
| Field and Description | Data Type | Max Length | Required? |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------|-------------------|-----------|
| **financialAccountId** The identifier of the financial account being tokenized. This could be a bank account number, or identifier or other types of financial accounts. | String (spaces not allowed) | 64 (min length 9) | Yes |
| **interbankCardAssociationId** The ID assigned by Mastercard to the financial institution. | Number | 11 (min length 3) | Yes |
| **countryCode** The country of the financial account. Expressed as a 3-letter (alpha-3) country code as defined in ISO 3166-1. | String | 3 (exact) | Yes |
The `AccountHolderData` object is a JSON structure containing the following fields.
| Field and Description | Data Type | Max Length | Required? |
|--------------------------------------------------------------------------------------------------------------|-----------|------------|-----------|
| **accountHolderName** The name of the account holder in the format LASTNAME/FIRSTNAME or FIRSTNAME LASTNAME. | String | 27 | Optional |
The `CardInfo` object is a JSON structure containing the following fields.
| Field and Description | Data Type | Max Length | Required? |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------|------------|-------------|
| **panUniqueReference** For repeat digitizations (when the issuer supports it), the unique reference is allocated to the Account PAN. When supplied, the tokenUniqueReferenceForPanInfo, accountNumber, expiryMonth and expiryYear are omitted from CardInfoData. Only allowed if tokenUniqueReferenceForPanInfo is not present and encryptedData does not contain the account information. | String | 64 | Conditional |
| **tokenUniqueReferenceForPanInfo** For repeat digitizations (when the issuer supports it), the unique reference allocated to the token will be provided to MDES and used to retrieve the account number and expiration date. When supplied, the panUniqueReference, accountNumber, expiryMonth and expiryYear are omitted from CardInfoData. Only allowed if panUniqueReference is not present and encryptedData does not contain the account information. | String | 64 | Conditional |
| **publicKeyFingerprint** The fingerprint of the public key used to encrypt the ephemeral AES key. | String. Hex-encoded data (case-insensitive). | 64 | Yes |
| **encryptedKey** One-time use AES key encrypted by the Mastercard encryption public key (as identified by 'publicKeyFingerprint') using the OAEP or PKCS#1 v1.5 scheme (depending on the value of 'oaepHashingAlgorithm'). Requirement is for at least a 128-bit key (with 256-bit key supported as an option). | String. Hex-encoded data (case-insensitive). | 512 | Yes |
| **oaepHashingAlgorithm** Hashing algorithm used with the OAEP scheme. Must be either: * SHA256 * SHA512
If omitted, PKCS#1 v1.5 is used. | String | 6 | No |
| **iv** The Initialization Vector (IV) is used when encrypting data using the one-time use AES key. Must be exactly 16 bytes (32-character hex string) to match the block size. If not present, an IV of zero is assumed. | String. Hex-encoded data (case-insensitive). | 32 (exact) | No |
| **encryptedData** Contains the encrypted CardInfoData object. Encrypted by the ephemeral AES key using CBC mode (IV as provided in 'iv', or zero if none is provided) and PKCS#7 padding. | String. Hex-encoded data (case-insensitive). | 256K | Yes |
The `CardInfoData` object is a JSON structure containing the following fields.
| Field and Description | Data Type | Max Length | Required? |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------|--------------------|-------------|
| **accountNumber** The Account PAN of the card to be digitized. Required unless panUniqueReference or tokenUniqueReferenceForPanInfo is provided in CardInfo. | String (numeric) | 19 (min length 12) | Conditional |
| **expiryMonth** The month of the expiration date of the card to be digitized. May be omitted if the card does not have a visible expiry date. The expiry date cannot be in the past. Not required if panUniqueReference or tokenUniqueReferenceForPanInfo is provided in CardInfo or the card does not have an expiry date. | String (numeric) | 2 (exact) | Conditional |
| **expiryYear** The year of the expiration date of the card to be digitized. May be omitted if the card does not have a visible expiry date. The expiry date cannot be in the past. Not required if panUniqueReference or tokenUniqueReferenceForPanInfo is provided in CardInfo or the card does not have an expiry date. | String (numeric) | 2 (exact) | Conditional |
| **source** The source of this card information. Must be: CARD_ADDED_VIA_APPLICATION | String | 32 | Yes |
| **cardholderName** The name of the cardholder in the format LASTNAME/FIRSTNAME or FIRSTNAME LASTNAME. Required unless panUniqueReference or tokenUniqueReferenceForPanInfo is provided in CardInfo. | String | 27 | Conditional |
| **billingAddress** The billing address for the card to be digitized. Verified as part of reaching the digitization decision. | BillingAddress object | N/A | No |
| **dataValidUntilTimestamp** The date/time after which this CardInfoData object is considered invalid. If present, all systems must reject this CardInfoData object after this time and treat it as invalid data. Must be expressed in ISO 8601 extended format as one of the following, where \[.sss\] is optional and can be 1--3 digits: * YYYY-MM-DDThh:mm:ss\[.sss\]Z * YYYY-MM-DDThh:mm:ss\[.sss\]±hh:mm
Must be a value no more than 30 days in the future. Mastercard recommends using a value of Current Time + 30 minutes. | String | 29 | No |
The `BillingAddress` object is a JSON structure containing the following fields.
| Field and Description | Data Type | Max Length | Required? |
|--------------------------------------------------------------------------------------------------------------------------|-----------|------------|-----------|
| **line1** The first line of the billing address. | String | 64 | No |
| **line2** The second line of the billing address. | String | 64 | No |
| **city** The city of the billing address. | String | 32 | No |
| **countrySubdivision** The country subdivision (for example, the state in the U.S.) of the billing address. | String | 12 | No |
| **postalCode** The postal code (for example, zipcode in the U.S.) of the billing address. | String | 16 | No |
| **country** The country of the billing address, expressed as a 3-letter (alpha-3) country code as defined in ISO 3166-1. | String | 3 (exact) | No |
## Encryption of Card Information {#encryption-of-card-information}
MDES receives card information in an encrypted format from an issuer via the Wallet Provider. For wallet providers other than Apple Pay, the wallet provider provides a simple pass-through mechanism for the encrypted data package. This ensures the security of sensitive data for wallet providers who typically do not wish to deploy technology needed to protect the card information in conformance with PCI-DSS standards.
The following diagram shows an example implementation where an issuer app communicates with a wallet provider's wallet application to initiate the digitization of the card:
##### Encrypted Data Flow
1. The issuer app uses proprietary APIs that link it to the issuer's server, where the encryption of the card details is performed.
2. The Wallet Provider publishes an API for the issuer to use to pass the encrypted card data to the wallet application.
3. The wallet application uses proprietary APIs to pass the encrypted card data to the Wallet Provider server.
4. The Wallet Provider server calls the MDES API to initiate the digitization request.
5. MDES identifies the key that was used to encrypt the data from the issuer and decrypts the card details.
Note: The pass-through mechanism described in this guide does not apply to Apple Pay; refer to the Apple Pay wallet API documentation.
While this diagram shows an app-based approach, an issuer and Wallet Provider may also communicate using server-to-server connections. For example, this would enable an issuer to initiate digitization of a card from an online banking website into a server-based Wallet Provider, such as a large online merchant who wants to use tokens to initiate transactions (merchant tokenization) rather than capturing card details from cardholders.
## Requesting the Mastercard Encryption Public Key {#requesting-the-mastercard-encryption-public-key}
For wallet providers other than Apple Pay, issuers must obtain the Mastercard RSA 2048-bit Public Key for encrypting their card details. Requesting the Public Key reuses existing Mastercard Key Management Services (KMS) but is mediated by the Mastercard Customer Implementation Services (CIS) team. Contact your CIS representative for more information on requesting the Mastercard encryption Public Key.
The issuer must insert the fingerprint of the Mastercard encryption Public Key into the publicKeyFingerprint field of the encryptedPayload field of the fundingAccountInfo object (or of the CardInfo object).
For Apple Pay, a different encryption key and process is used; refer to the Apple Pay wallet API documentation.
## Encrypting the Ephemeral AES Key {#encrypting-the-ephemeral-aes-key}
To create the encryptedKey field in the encryptedPayload field of the fundingAccountInfo object (or in the CardInfo object), the issuer:
1. Generates a random 128-bit or 256-bit ephemeral AES key.
2. Determines the hashing algorithm to use with the OAEP scheme (SHA-256 or SHA-512) and indicates the choice in the oaepHashingAlgorithm field in the encryptedPayload field of the fundingAccountInfo object (or in the CardInfo object).
3. Encrypts the AES key with the Mastercard encryption public key using the OAEP or PKCS#1 v1.5 scheme, depending on the chosen hash algorithm.
##### Cipher Block Chaining (CBC) Mode Encryption
## TAV Creation {#tav-creation}
The Tokenization Authentication Value (TAV) is a base64-encoded JSON structure of data. For details, refer to [MDES Issuer Implementation Guide](https://techdocs.mastercard.com/bundle/m_MIIG/page/c_MIIG_TAVEncoding.html)