# API Basics source: https://developer.mastercard.com/mastercard-processing-authentication/documentation/api-basics/index.md ## Overview {#overview} The Mastercard Processing Authentication Hub APIs follow Representational State Transfer (REST) principles. The APIs have predictable resource-oriented URLs, accept JavaScript Object Notation ([JSON](https://www.json.org/json-en.html)) request bodies, return JSON-encoded responses, and use standard Hypertext Transfer Protocol (HTTP) response codes, authentication, and verbs. The Mastercard Processing Authentication Hub APIs use HTTPS to ensure data privacy, but HTTPS with TLS versions below v1.2 is not supported. All `POST` requests must include the header `Content-Type` of `application/json;charset=utf-8`, and the body for all requests must be a valid JSON object. ## Correlation-ID {#correlation-id} The Mastercard Processing platform dynamically generates a universally unique identifier (UUID) and assigns it to the request header `X-MC-Correlation-ID`. The UUID is always added to the response header to provide end-to-end traceability. In addition to the `X-MC-Correlation-ID`, you can generate your request identifier and pass it in the `Correlation-ID` header. It is recommended to generate a UUID in compliance with [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122). ## Environments {#environments} The following table describes the different environments that are available. | Environment | Description | |--------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Sandbox | An early-access environment containing limited-capacity mock APIs enables you to test the APIs quickly to assist with initial integration and solution development. The Sandbox returns mock responses for a defined request (see [Sandbox testing](https://developer.mastercard.com/mastercard-processing-authentication/documentation/sandbox-testing/index.md)) and should not be used for complete integration testing. Use your Sandbox keys to authenticate with this environment. The keys are set up when you [create your project in the Mastercard Developer portal](https://developer.mastercard.com/mastercard-processing-authentication/tutorial/create-sandbox-apis/index.md). | | Mastercard Test Facility (MTF) | The MTF environment provides access to the latest production release version of APIs to conduct full User Acceptance Tests (UAT) before moving to production. It supports end-to-end testing of product functionality through API, batch, and GUI interfaces. MTF is maintained and supported by Mastercard Processing, ensuring it remains functionally aligned with the production environment. Access to the MTF environment is included as part of the onboarding and implementation process offered by Mastercard Processing. Use your Sandbox keys to authenticate with this environment. The keys are set up when you [create your project in the Mastercard Developer portal](https://developer.mastercard.com/mastercard-processing-authentication/tutorial/create-sandbox-apis/index.md). | | Production | A complete production environment containing the latest production API release. Use your Production keys to authenticate with this environment. The keys are set up when you [request Production access](https://developer.mastercard.com/mastercard-processing-authentication/tutorial/move-project-to-production/index.md) for your project (through your project page). | ## Connection and Integration {#connection-and-integration} There are two ways of integrating with the Mastercard Processing Authentication Hub API: * **API client generated by Mastercard:** Create a customizable API client from the Mastercard Processing OpenAPI Specification (OAS) and let the Mastercard open-source client libraries handle authentication for you. This approach offers more flexibility and is strongly recommended. See the [Generating and Configuring a Mastercard API Client](https://developer.mastercard.com/platform/documentation/security-and-authentication/generating-and-configuring-a-mastercard-api-client/) tutorial for more information. * **Method of your choice:** Use the REST/HTTP client of your choice and leverage the Mastercard open-source [client libraries](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/#client-libraries) for signing your requests and dealing with payload encryption. For more information, see [API Reference](https://developer.mastercard.com/mastercard-processing-authentication/documentation/api-reference/index.md). Tip: Refer to the [Build an end-to-end application](https://developer.mastercard.com/mastercard-processing-core/tutorial/build-end-to-end-app/) tutorial of the Core API to help you with building an end-to-end application. ## Authentication {#authentication} ### Inbound calls {#inbound-calls} For inbound calls, the Mastercard Processing Authentication Hub API uses one-legged OAuth 1.0a for authentication and authorization of client applications. For more information, refer to [Using OAuth 1.0a to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/). We highly recommend using the Mastercard [client authentication libraries](https://github.com/Mastercard?q=oauth) available in several popular programming languages. ### Outbound calls {#outbound-calls} For outbound calls sent from the Mastercard Processing to your exposed endpoint, the defined endpoint must be capable of receiving an HTTPS POST of JSON data and must support the mutual TLS (mTLS) authentication protocol. You must install the following root certificates in your trust store: * [DigiCert Assured ID Client CA G2](https://www.digicert.com/kb/digicert-root-certificates.htm#roots:~:text=0F%3AFA%3AE1%3AF3%3A1A%3A2B%3A43%3A3C%3A3D%3A9A%3AE1%3A6D%3A64%3A3B%3A58%3A8B) * [DigiCert Assured ID Root G2](https://www.digicert.com/kb/digicert-root-certificates.htm#roots:~:text=expired%20%C2%A0%C2%A0revoked-,DigiCert%20Assured%20ID%20Root%20G2,-Download%20PEM%20%7C) Mastercard Processing Authentication API sends only the client certificate and the intermediate certificate during the mTLS handshake, so your server must already trust the corresponding Root CA. Mastercard Processing recommends you rely on the CA-trusted method of verification. This approach enables a comparatively smoother implementation or renewal of certificates in the future. The Mastercard Processing Authentication API needs to trust your Certificate Authority (CA). Below is the list of CAs supported by Mastercard Processing Authentication Hub APIs. CN=DigiCert Global Root G2,OU=www.digicert.com,O=DigiCert Inc,C=US CN=DigiCert Global Root CA,OU=www.digicert.com,O=DigiCert Inc,C=US CN=VeriSign Universal Root Certification Authority,OU=(c) 2008 VeriSign\, Inc. - For authorized use only,OU=VeriSign Trust Network,O=VeriSign\, Inc.,C=US CN=COMODO RSA Certification Authority,O=COMODO CA Limited,L=Salford,ST=Greater Manchester,C=GB CN=SSL.com Root Certification Authority ECC,O=SSL Corporation,L=Houston,ST=Texas,C=US CN=COMODO Certification Authority,O=COMODO CA Limited,L=Salford,ST=Greater Manchester,C=GB CN=DigiCert High Assurance EV Root CA,OU=www.digicert.com,O=DigiCert Inc,C=US CN=GeoTrust Global CA,O=GeoTrust Inc.,C=US CN=Go Daddy Root Certificate Authority - G2,O=GoDaddy.com\, Inc.,L=Scottsdale,ST=Arizona,C=US CN=SecureTrust CA,O=SecureTrust Corporation,C=US CN=Verizon Global Root CA,OU=OmniRoot,O=Verizon Business,C=US CN=Certum Trusted Network CA,OU=Certum Certification Authority,O=Unizeto Technologies S.A.,C=PL CN=VeriSign Class 3 Public Primary Certification Authority - G5,OU=(c) 2006 VeriSign\, Inc. - For authorized use only,OU=VeriSign Trust Network,O=VeriSign\, Inc.,C=US CN=Entrust Root Certification Authority - G2,OU=(c) 2009 Entrust\, Inc. - for authorized use only,OU=See www.entrust.net/legal-terms,O=Entrust\, Inc.,C=US CN=AAA Certificate Services,O=Comodo CA Limited,L=Salford,ST=Greater Manchester,C=GB CN=GlobalSign,O=GlobalSign,OU=GlobalSign Root CA - R3 CN=Baltimore CyberTrust Root,OU=CyberTrust,O=Baltimore,C=IE CN=Actalis Authentication Root CA,O=Actalis S.p.A./03358520967,L=Milan,C=IT CN=Certum Extended Validation CA SHA2,OU=Certum Certification Authority,O=Unizeto Technologies S.A.,C=PL CN=DST Root CA X3,O=Digital Signature Trust Co. CN=GeoTrust Primary Certification Authority - G3,OU=(c) 2008 GeoTrust Inc. - For authorized use only,O=GeoTrust Inc.,C=US CN=Thawte RSA CA 2018,OU=www.digicert.com,O=DigiCert Inc,C=US CN=GlobalSign Root CA,OU=Root CA,O=GlobalSign nv-sa,C=BE CN=Wells Fargo Root Certification Authority 01 G2,OU=Wells Fargo Certification Authority,O=Wells Fargo,C=US CN=Visa eCommerce Root,OU=Visa International Service Association,O=VISA,C=US CN=Starfield Services Root Certificate Authority - G2,O=Starfield Technologies\, Inc.,L=Scottsdale,ST=Arizona,C=US CN=Gemalto Business Root Certificate Authority,O=Gemalto,L=Tours,C=FR CN=Gemalto Business Solutions Certificate Authority,O=Gemalto,L=Tours,C=FR OU=Starfield Class 2 Certification Authority,O=Starfield Technologies\, Inc.,C=US CN=StartCom Certification Authority,OU=Secure Digital Certificate Signing,O=StartCom Ltd.,C=IL CN=SwissSign Silver CA - G2,O=SwissSign AG,C=CH CN=Entrust Certification Authority - L1K,OU=(c) 2012 Entrust\, Inc. - for authorized use only,OU=See www.entrust.net/legal-terms,O=Entrust\, Inc.,C=US CN=GlobalSign,O=GlobalSign,OU=GlobalSign Root CA - R2 CN=Entrust.net Certification Authority (2048),OU=(c) 1999 Entrust.net Limited,OU=www.entrust.net/CPS_2048 incorp. by ref. (limits liab.),O=Entrust.net OU=Go Daddy Class 2 Certification Authority,O=The Go Daddy Group\, Inc.,C=US CN=thawte Primary Root CA,OU=(c) 2006 thawte\, Inc. - For authorized use only,OU=Certification Services Division,O=thawte\, Inc.,C=US CN=Microsoft IT TLS CA 2,OU=Microsoft IT,O=Microsoft Corporation,L=Redmond,ST=Washington,C=US CN=UL TS 3D-Secure ROOT CA,OU=UL TS 3D-Secure ROOT CA,O=UL Transaction Security division,C=NL CN=GeoTrust Primary Certification Authority,O=GeoTrust Inc.,C=US CN=GTS Root R2,O=Google Trust Services LLC,C=US CN=Entrust Root Certification Authority,OU=(c) 2006 Entrust\, Inc.,OU=www.entrust.net/CPS is incorporated by reference,O=Entrust\, Inc.,C=US OU=Security Communication RootCA2,O=SECOM Trust Systems CO.\,LTD.,C=JP CN=thawte Primary Root CA - G3,OU=(c) 2008 thawte\, Inc. - For authorized use only,OU=Certification Services Division,O=thawte\, Inc.,C=US Note: During implementation, you must provide the public endpoint where Mastercard Processing Authentication API requests will be sent. You must provide this information to your Mastercard Product Delivery or Customer Implementation Services Implementation Manager. Only the FQDN is needed, as the context path is fixed in the OpenAPI specification. Outbound calls will be sent to your endpoint on the standard HTTPS port (443). For example, all `acsAReq` calls will be sent to: `https://issuer-host-name.com:443/three-ds-transactions/{three_ds_server_transaction_id}/acs-authentication-requests`, where `{three_ds_server_transaction_id}` is a unique transaction identifier assigned by the 3DS Server. **Ensure that the endpoint is accessible over the Internet on port 443 to complete API setup on the Mastercard Processing side.** Alert: There is a 3-second timeout set at the Mastercard API Gateway level for all outbound calls. However, it is strongly recommended to ensure that your endpoint responds quickly, within 1.5 seconds, to prevent the 3DS secure transaction from failing due to a timeout on the ACS or DS side. ## Encryption {#encryption} ### Inbound calls {#inbound-calls-1} For inbound calls, the transport between client applications and Mastercard is secured using [TLS/SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security), which means data is encrypted by default when transmitted across networks. In addition, the Mastercard Processing Authentication Hub API uses [JSON Web Encryption (JWE)](https://datatracker.ietf.org/doc/html/rfc7516) to provide end-to-end payload encryption to secure sensitive data like Personally Identifiable Information (PII). You can manage your encryption keys using your [Developer Dashboard](https://developer.mastercard.com/dashboard). To learn more, refer to our [Securing Sensitive Data Using Payload Encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/#overview) guides. We highly recommend using Mastercard client [encryption libraries](https://github.com/Mastercard?q=client-encryption) available in several popular programming languages. For these, you will need a configuration object as follows (to be used at the [JWE - Create encryption keys](https://developer.mastercard.com/mastercard-processing-authentication/tutorial/create-sandbox-apis/step6/index.md) step): * Java * C# ```java // change these values accordingly String clientEncryptionCertPath = "#PATH AND NAME OF YOUR PEM FILE HERE#"; String mastercardEncryptionKeyFilePath = "#PATH AND NAME OF YOUR P12 FILE HERE#"; String mastercardEncryptionAlias = "#YOUR KEY ALIAS HERE#"; String mastercardEncryptionPass = "#YOUR KEY PASSWORD HERE#"; // This will be the certificate used to encrypt the payload before sending Certificate encryptionCertificate = EncryptionUtils.loadEncryptionCertificate(clientEncryptionCertPath); // The response received from the call will need to be decrypted using this key PrivateKey decryptionKey = EncryptionUtils.loadDecryptionKey( mastercardEncryptionKeyFilePath, mastercardEncryptionAlias, mastercardEncryptionPass); // Prepare JweConfig JweConfig config = JweConfigBuilder.aJweEncryptionConfig() .withEncryptionCertificate(encryptionCertificate) .withDecryptionKey(decryptionKey) .withEncryptionPath("$", "$") .withDecryptionPath("$.encryptedValue", "$") .withEncryptedValueFieldName("encryptedValue") .build(); ``` ```csharp // change these values accordingly var clientEncryptionCertPath = "#PATH AND NAME OF YOUR PEM FILE HERE#"; var mastercardEncryptionKeyFilePath = "#PATH AND NAME OF YOUR P12 FILE HERE#"; var mastercardEncryptionAlias = "#YOUR KEY ALIAS HERE#"; var mastercardEncryptionPass = "#YOUR KEY PASSWORD HERE#"; // This will be the certificate used to encrypt the payload before sending var encryptionCertificate = EncryptionUtils.loadEncryptionCertificate(clientEncryptionCertPath); // The response received from the call will need to be decrypted using this key var decryptionKey = EncryptionUtils.loadDecryptionKey( mastercardEncryptionKeyFilePath, mastercardEncryptionAlias, mastercardEncryptionPass); // Prepare JweConfig var config = JweConfigBuilder.AJweEncryptionConfig() .WithEncryptionCertificate(encryptionCertificate) .WithDecryptionKey(decryptionKey) .WithEncryptionPath("$", "$") .WithDecryptionPath("$.encryptedValue", "$") .WithEncryptedValueFieldName("encryptedValue") .Build(); ```
Tip: To learn how to build an API application with JWE, refer to the [Build an end-to-end application](https://developer.mastercard.com/mastercard-processing-core/tutorial/build-end-to-end-app/) tutorial for the Core API. ### Outbound calls {#outbound-calls-1} For outbound calls, the payload is not encrypted with JWE. The mutual TLS (mTLS) is used to enable you to trust the Mastercard Processing Authentication Hub API before receiving notifications. ## API Configuration {#api-configuration} The Mastercard Processing Authentication Hub API enables a customized configuration for each issuer to align with specific requirements. A part of the API configuration is also a list of `operationId` enabled for each issuer. The list depends on the product that the issuer wants to implement. Note: If you try to execute the `operationId` that is disabled in your API configuration, you will receive a dedicated error. For more information about error messages, see [Error Codes](https://developer.mastercard.com/mastercard-processing-authentication/documentation/code-and-formats/index.md). The API allows limiting or extending the available characters or setting a specific mask for sending the data, such as PAN. ## Versioning (Must Read) {#versioning-must-read} As per Mastercard standards, the Mastercard Processing Authentication Hub APIs do not have any versioning in interfaces to ensure backward compatibility and avoid breaking changes. Here is a list of what can be considered breaking and non-breaking changes. | Backward-compatible (non-breaking) changes | Backward-incompatible (breaking) changes | |--------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------| | Adding an API interface to an API service | Removing or renaming a service, interface, field, method, or enum value | | Adding a method to an API interface | Changing an HTTP binding | | Adding an HTTP binding to a method | Changing the data type of a field | | **Adding a field (an optional field or contains a default value) to an inbound request message** | Changing a resource name format | | **Adding a field to a response message or outbound request** | Changing the visible behavior of existing requests | | Adding an output-only resource field | Changing the URL format in the HTTP definition | | Adding a new optional query parameter with a default value (?parameter=value) | Adding a read or write field to a resource message | | Adding an HTTP header field to a request/response message | Modifications (adding or modifying) a value to an enum in a response | | Adding a new error code | Adding a new mandatory field to an inbound request message without setting a field default value | The listed items are not comprehensive. It only indicates what can be considered a breaking or non-breaking change. Alert: You must adhere to these guidelines by writing an application in a way that backward-compatible changes (for example, adding a new field to a response) will not cause errors on your side. Mastercard Processing provides a minimum of 3 months' notice for changes to the APIs.