# Mastercard Processing Authentication Hub APIs source: https://developer.mastercard.com/mastercard-processing-authentication/documentation/index.md ## Overview {#overview} The Mastercard Processing Authentication API provides a certified global Access Control Server (ACS) solution for secure online transactions using 3D Secure for the cards issued with the Mastercard Processing Core API. Issuers can use the API for 3DS transaction authentication with any authentication solution already offered to the cardholders, including biometrics. Backed by one of the top ACS providers on the market, Mastercard Processing securely forwards authentication requests and responses between the issuer and the ACS, ensuring smooth communication through its infrastructure. With the Mastercard Processing Authentication Hub API, you have the following benefits: * Easy integration with the ACS, vendor cooperating with Mastercard Processing. * PAN-less issuer support. * Your authentication methods through: * your banking app. * your website. * The ability to send a one-time passcode (OTP) by yourself instead of ACS, which gives you better control over your customer experience. ## How it Works {#how-it-works} Each card payment transaction is preceded by authentication. Authentication is a process of confirming a customer's identity through at least one of the following authentication factors: * Knowledge * Inherence * Ownership Knowledge is the most common category used for transaction authentication. In some cases, the authentication process finishes early when there is no need to challenge a cardholder (so-called frictionless authentication). A special security standard for e-commerce transactions, called Three-Domain Secure (3DS), was developed for security reasons. ### Three-Domain Secure {#three-domain-secure} Three-Domain Secure or 3D-Secure (3DS) is a messaging protocol that enables cardholders to authenticate with the card directly while shopping online. This protocol was created by Payment Schemes in 2001 and was used to provide improved security for Internet payments. The name 3D comes from the three-domain model that provides the additional layer of secure authentication between the financial authorization process and the online authentication process. The three 3DS domains are: * Acquirer Domain: It refers to the acquirer and the merchant receiving the transaction payment. The merchant uses the 3DS Client and is connected to the 3DS Server. * Interoperability Domain: It refers to the infrastructure that is used to support the 3DS. The infrastructure is usually provided by a payment scheme, and it is called a Directory Server (DS). The DS routes authentication between the acquirer domain (3DS Server) and the issuer domain (ACS). * Issuer Domain: It refers to the financial institution that issued the payment card, which is used for the transaction. The issuer is supported by the Access Control Server (ACS). ![Authentication process](https://static.developer.mastercard.com/content/mastercard-processing-authentication/uploads/auth-how-it-works.png) The 3D-Secure authentication process actors are as follows: * Cardholder: The cardholder initiates the e-commerce payment process. * Merchant: The merchant sends transaction details to the 3DS Server, and the data sent by the merchant will be included in the authentication request message. * 3DS Server: The 3DS Server creates and sends the authentication request message to the Directory Server (DS). * Directory Server (DS): The DS is a part of the Mastercard ID Check solution. It analyses the message from the 3DS Server, adds a risk score to the message (optional), and routes the message to the proper ACS. * ACS: The ACS evaluates the data provided in the authentication request message. The ACS determines what type of cardholder authentication method is required and which party (ACS or issuer) will perform it. If it is defined as ACS responsibility, the ACS performs cardholder authentication. Rules are defined during the issuer's onboarding. One of the possible authentication methods is frictionless, wherein no additional cardholder authentication is required. In such cases, the authentication flow stops on the ACS. * Mastercard Processing Authentication Hub API: The Authentication Hub API forwards messages from the ACS to the issuer and vice versa. The Authentication Hub can mask PAN in communication with the issuer and add a technical card ID (`cardContractId`), which supports PAN-less issuers. * Issuer: The issuer decides which authentication method should be performed and, optionally, performs the cardholder authentication. In the use cases section, you will find listed authentication methods that the Mastercard Processing Authentication API supports. Note: The current version of the Mastercard Processing Authentication Hub API supports version 2.2 of 3DS and will be updated along with 3DS upgrades to higher versions in the future.
## 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** | |----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 2FA | Two-factor authentication, referred to as two-step verification or dual-factor authentication, is a security process in which users provide two different authentication factors to verify themselves. | | 3DS | 3D-Secure or Three Domain Secure is the service provided by the ACS provider. It is designed to be an additional security layer for e-commerce transactions. The three domains are the acquirer domain, issuer domain, and interoperability domain (for example, Payment Schemes). | | 3DS Server | It refers to the 3DS Integrator's server or systems that handle online transactions and facilitate communication between the 3DS Requestor and the DS. | | 3DS Requestor | It is the initiator of the EMV 3D-Secure authentication request. For example, it may be a merchant or a digital wallet requesting authentication within a purchase flow. | | ACS | Access Control Server is the main component of the 3DS service provided by the ACS provider. It is responsible for the transaction authentication secured with a one-time passcode (OTP). It generates and validates OTPs to authenticate 3DS transactions correctly. | | Acquirer | It is the financial institution that establishes a contractual service relationship with a merchant to accept card payments. In the context of 3DS, in addition to the traditional role of receiving and sending authorization and settlement messages (entering transactions into interchange), the acquirer also determines whether the merchant is eligible to support the merchant's participation in 3D-Secure. | | Authentication | In the context of 3DS, authentication is the process of confirming that the person making an e-commerce transaction is entitled to use the payment card. | | Authorization | It is the process by which the issuer or a processor on the issuer's behalf approves a transaction for payment. | | Cardholder | An individual who is the card user is usually also the card owner. | | CNP | Card-Not-Present is a transaction made without using a physical card, also called an e-commerce transaction. | | CMS | Card Management System | | DS | Directory Server is a server component operated in the Interoperability Domain. It performs a number of functions that include authenticating the 3DS Server, routing messages between the 3DS Server and the ACS, and validating the 3DS Server. | | EMV | It refers to EMVCo's specifications for global interoperability and acceptance of secure payment transactions and products and services complying with such specifications. | | Merchant | It is the entity that contacts an acquirer to accept payment cards. It manages the online shopping experience with a cardholder, obtains a card number, and then transfers control to the 3DS Server, which conducts the payment authentication. | | OTP | A one-time passcode is a password generated by ACS that is valid for only one login session or transaction on a computer system or other digital device. | | PAN | Primary Account Number is usually a 16-digit number, which uniquely identifies every card contract and is embossed on the card plastic. The beginning of the card number contains the Bank Identification Number (BIN), which allows for proper routing by payment schemes. | | RBA | Risk-based authentication is a non-static authentication approach that considers the risk profile associated with a transaction. | | SCA | Strong customer authentication is authentication based on the use of two or more elements categorized as knowledge (something only the user knows), possession (something only the user possesses), and inherence (something the user is). These must be independent of one another in that the breach of one does not compromise the reliability of the others and is designed in such a way as to protect the confidentiality of the authentication data. | | TRA | Transaction risk analysis is one of the SCA exemptions based on transaction-related circumstances, such as user's location, hint for malware software, and behavior analysis. | ### Formatting Conventions {#formatting-conventions} We use plain text names for our system objects (for example, account contracts). 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: `cardContractNumber`. * Defined values you put into API requests or receive in API responses: `3c`. * API methods and operationIds: `PUT`, `acsAReq`. * Actors: issuer, processor, payment scheme, 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` 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, `acsAReq`). | The Mastercard Processing Digital API specification uses the following case format: | Term | Case | Example | |-----------------|------------|--------------------------------| | Property names | camelCase | cardContractNumber | | Path parameters | snake_case | three_ds_server_transaction_id | | Path segments | kebab-case | /three-ds-transactions | ## 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-authentication/documentation/api-basics/index.md) to learn more about authentication and encryption. * Review the [Use Cases](https://developer.mastercard.com/mastercard-processing-authentication/documentation/use-cases/index.md), their implementations, and sequence diagrams. * Use the [API Reference](https://developer.mastercard.com/mastercard-processing-authentication/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-authentication/documentation/code-and-formats/index.md) and the formats that we use. * See [Support](https://developer.mastercard.com/mastercard-processing-authentication/documentation/support/index.md) in case of questions or support.