# Mastercard Processing Digital APIs source: https://developer.mastercard.com/mastercard-processing-digital/documentation/index.md ## Overview {#overview} Mastercard Processing Digital API supports you in utilizing Mastercard Digital Enablement Service (MDES) functionalities. The Digital API is applicable when Mastercard Processing: * Acts as an issuer processor. * Takes part in the digitization process. You integrate with Mastercard Processing, and Mastercard Processing performs the following actions: * It communicates on your behalf during the exchange of pre-digitization messages and applies a set of default rules supporting the tokenization process. * It configures as chosen by your cardholder identification and verification methods (ID\&V). * It recognizes and processes authorization of transactions using tokens. This model is especially valuable for PAN-less issuers who use technical identifiers instead of full PAN. ## Glossary and Conventions {#glossary-and-conventions} ### Glossary {#glossary} The glossary explains the various terms and definitions, and the acronyms used throughout this documentation. | **Term** | **Definition** | |---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ACN | Activation Code Notification is a pre-digitization message generated by MDES. ACN contains the Activation Code, a random numeric value generated for each digitization, but only when required. | | API | Application Programming Interface | | BIN | Bank Identification Number | | Cardholder | An individual who is the card user is usually also the card owner. | | CBS | The Core Banking System is the issuer's server. | | CMS | Card Management System | | CVC2 | Card Verification Code 2 is a unique number linked to each card and printed on a physical card. It is shown in the application when a card is virtual and required during online payments. | | In-app provisioning | A mechanism that allows issuers to add xPay functionality from the issuer's mobile application. In the issuer's mobile application, the cardholder selects the card to be digitized and pushed to the Wallet Provider application to continue tokenization. It eliminates the need for a cardholder to enter the card details in the wallet manually. | | In-app verification | A process where the cardholder authenticates in the issuer application to activate the token initiated in the token requestor application. | | IIDD | Issuer-Initiated Digitization Data is the encrypted card data signed with TAV signature. | | ID\&V | Identification and Verification are the methods used in the authentication process. | | Issuer | The institution, bank, or fintech that issues a card. | | JSON | JavaScript Object Notation | | JWE | JSON Web Encryption | | MDES | Mastercard Digital Enablement Service is a token platform that allows issuers to securely store payment card credentials on mobile devices or merchant servers. | | MP | Mastercard Processing is a processor. | | operationId | It is a unique name for a particular API operation. It is usually in the form of text expressing the name of an operation (for example, `getTokensByClient`). | | OAS | The OpenAPI Specification is the documentation of an API constructed by the Open API 3.0 standard. | | OTP | One-time password. This documentation describes a way of delivering an Activation Code to a cardholder. Available scenarios are OTP through SMS (may be supported by Mastercard Processing or issuer) and OTP through e-mail (may be supported by the issuer). | | PAN | Primary Account Number | | PCI DSS | Payment Card Industry Data Security Standard | | Processor | It is a company providing services for issuers related to card issuance, card management, and processing transactions. | | T\&C | Issuer terms and conditions | | TAR | Tokenization Authorization Request is a pre-digitization message generated by MDES. TAR is the pre-digitization message initiating the tokenization process. | | TAV | Tokenization Authentication Value is the Base64-encoded JSON structure of data containing a digital signature. | | TCN | Tokenization Complete Notification is a pre-digitization message generated by MDES. TCN contains information about successful tokenization. | | Token | A surrogate PAN substituted for the real PAN (the funding PAN). | | Token requestor | It is an entity, such as a wallet provider, merchant, or issuer that uses MDES for token requests and token transactions. It is directly integrated with MDES. | | TRID | Token Requestor ID is an identifier of Token Requestor. | | TVN | Tokenization Event Notification is a pre-digitization message generated by MDES. TVN contains information about token state changes or errors that occurred during the tokenization process. | | WID | Wallet ID is the identifier of wallet application, program, or service associated with the Token Requestor or Wallet Provider. | | WP | Wallet Provider provides wallet applications for cardholders to digitize their cards and make digital payments. Wallet Providers can provide wallets for their devices (such as smartphones, smartwatches, and fitness bands) or partner with device manufacturers. | ### Formatting Conventions {#formatting-conventions} We use plain text names for our system objects (for example, account contract). For technical descriptions, we frame words in adherence to the OpenAPI Specification (OAS) naming conventions. Framed words can refer to: * API objects: `Client` * Field names required in API requests: `tokenNumber`. * Defined values you put into API requests or receive in API responses: `ACTIVE`. * API methods and operationIds: `PUT`, `getTokenByNumber`. * Actors: issuer, processor, payment network, personalization bureau, and cardholder are in lower-case letters. ### REST Naming Conventions {#rest-naming-conventions} | **Term** | **Definition** | |-------------|----------------------------------------------------------------------------------------------------------| | method | An HTTP request method, such as `POST`, `GET`, or `PUT`. | | operation | A specific procedure that is invoked on an object using a method. | | endpoint | A path or address that the API exposes for your requests. A single path can support multiple operations. | | operationId | A unique name used to identify a specific operation (for example, `getTokenByNumber`). | The Mastercard Processing Digital API specification uses the following case format: | Term | Case | Example | |------------------|------------|-----------------------------| | Property names | camelCase | tokenNumber | | Path parameters | snake_case | client_id | | Query parameters | snake_case | status in getTokensByClient | | Path segments | kebab-case | /token-relinks | ## How It Works {#how-it-works} Integration with MDES and a full range of Mastercard Processing services connected to digital products, such as tokenization and token management, can be done by different interfaces. ![](https://static.developer.mastercard.com/content/mastercard-processing-digital/uploads/how-it-works-digital-services.png) The use cases enabled through Mastercard Processing Digital API are as follows: * **Token management** You can retrieve information about tokens linked to a specific client and all their cards or only a specific card contract, with additional selection based on its status. Also, detailed information about a single token can be obtained, including token status, wallet, and device type. You can change the token status to a desired value according to one or all tokens under a specific card contract. It is beneficial when you want to allow a cardholder to manage token status in the mobile application. Changing card contract status affects the token status automatically; it is updated by Mastercard Processing immediately. You can also relink tokens to another card contract. However, after card renewal or replacement, Mastercard Processing automatically relinks tokens. * **Tokenization initiated in your mobile application (in-app provisioning)** The issuer's application is nowadays the most important way of communication with cardholders. A cardholder can digitize the card in the application, so there is no need to enter card data manually. It might sound simple, but there are plenty of options for user experience design. Mastercard Processing provides the necessary data to perform in-app provisioning to support you (especially if you are a PAN-less issuer) in creating the flows you like the most. When the cardholder logs into the application and chooses the card to be enrolled into the wallet, the application and wallet communicate in the background. The wallet passes the received data to MDES to start the tokenization process. The object with data sent from the application to the wallet and then to MDES is called Issuer-Initiated Digitization Data (IIDD). The data required for in-app provisioning can be generated directly by you but might be generated for you by Mastercard Processing (mandatory if you are a PAN-less issuer). It contains: * Encrypted card data: It contains mandatory and conditional data, such as PAN, card expiry date, source of account information (for example, the banking app), and data related to encryption. * Tokenization Authentication Value (TAV): It contains a digital signature created using an asymmetric key based on PAN and expiry date. TAV pre-authorizes digitization for a particular card to be digitized before token allocation. There are separate operations for generating IIDD -- one for Android devices and a second for Apple. In addition, there is an API that supports PAN-less issuers with in-app provisioning to Click to Pay. It returns an encrypted payload containing the PAN, which is needed for the MDES Token Connect flow. * **Tokenization initiated in the wallet with authentication in your mobile application (in-app verification)** When the cardholder starts the digitization process from the wallet and chooses the application to authenticate token activation, you can either activate the token leveraging [MDES Customer Service API](https://developer.mastercard.com/mdes-customer-service/documentation/use-cases/tokenactivate-use-case/), or you can use Mastercard Processing Digital API to generate TAV and send it back to the wallet to activate the token in MDES. Note: To provide IIDD and TAV objects, Mastercard Processing must exchange encryption keys with MDES on your behalf. ## Next Steps {#next-steps} * Review the [Quick Start Guide](https://developer.mastercard.com/platform/documentation/getting-started-with-mastercard-apis/quick-start-guide/) to learn how to use the Mastercard Developers platform. * See [API Basics](https://developer.mastercard.com/mastercard-processing-digital/documentation/api-basics-section/index.md) to learn more about authentication and encryption. * Review the [Use Cases](https://developer.mastercard.com/mastercard-processing-digital/documentation/use-cases/index.md), their implementations, and sequence diagrams. * Use the [API Reference](https://developer.mastercard.com/mastercard-processing-digital/documentation/api-reference/index.md) to review the OpenAPI Specification and execute each API endpoint. * Review the [Error Codes](https://developer.mastercard.com/mastercard-processing-digital/documentation/code-and-formats/index.md) and the formats that we use. * See [Support](https://developer.mastercard.com/mastercard-processing-digital/documentation/support/index.md) in case of questions or support.