# API Basics source: https://developer.mastercard.com/transaction-notifications/documentation/api-basics/index.md ## Client Authentication {#client-authentication} Mastercard uses OAuth 1.0a to authenticate your application. Mastercard provides [client authentication libraries](https://github.com/Mastercard?q=oauth) in several languages that you can integrate into your project or use as reference OAuth 1.0a implementations: | | ![Java](https://static.developer.mastercard.com/content/transaction-notifications/img/java.svg) **Java** | ![C#](https://static.developer.mastercard.com/content/transaction-notifications/img/csharp.svg) **C#** | ![Python](https://static.developer.mastercard.com/content/transaction-notifications/img/python.svg) **Python** | ![NodeJS](https://static.developer.mastercard.com/content/transaction-notifications/img/nodejs.svg) **NodeJS** | ![Go](https://static.developer.mastercard.com/content/transaction-notifications/img/go.svg) **Go** | |:--------------------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:------------------------------------------------------------------------------------------------------------------------------------------------------:|:-------------------------------------------------------------------------------------------------------------------------------------------------------:|:-------------------------------------------------------------------------------------------------------------------------------------------------------------:| | **Download/install** | [![](https://img.shields.io/maven-central/v/com.mastercard.developer/oauth1-signer.svg?style=flat&color=f99f1c&label=)](https://search.maven.org/artifact/com.mastercard.developer/oauth1-signer/) | [![](https://img.shields.io/nuget/v/Mastercard.Developer.OAuth1Signer.Core.svg?style=flat&color=f99f1c&label=)](https://www.nuget.org/packages/Mastercard.Developer.OAuth1Signer.RestSharpV2/) | [![](https://img.shields.io/pypi/v/mastercard-oauth1-signer.svg?style=flat&color=f99f1c&label=)](https://pypi.org/project/mastercard-oauth1-signer/) | [![](https://img.shields.io/npm/v/mastercard-oauth1-signer.svg?style=flat&color=f99f1c&label=)](https://www.npmjs.com/package/mastercard-oauth1-signer) | [![](https://img.shields.io/github/v/release/mastercard/oauth1-signer-go.svg?style=flat&color=f99f1c&label=)](https://github.com/Mastercard/oauth1-signer-go) | | **View on GitHub** | [![](https://img.shields.io/github/stars/mastercard/oauth1-signer-java.svg?label=&style=social)](https://github.com/Mastercard/oauth1-signer-java) | [![](https://img.shields.io/github/stars/mastercard/oauth1-signer-csharp.svg?label=&style=social)](https://github.com/Mastercard/oauth1-signer-csharp) | [![](https://img.shields.io/github/stars/mastercard/oauth1-signer-python.svg?label=&style=social)](https://github.com/Mastercard/oauth1-signer-python) | [![](https://img.shields.io/github/stars/mastercard/oauth1-signer-nodejs.svg?label=&style=social)](https://github.com/Mastercard/oauth1-signer-nodejs) | [![](https://img.shields.io/github/stars/mastercard/oauth1-signer-go.svg?label=&style=social)](https://github.com/Mastercard/oauth1-signer-go) | For more information, see [Using OAuth 1.0a to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/authentication/using-oauth-1a-to-access-mastercard-apis/). ## Transport Encryption {#transport-encryption} 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. Transaction Notifications webhook delivery uses HTTPS with mutual TLS (MTLS). Outbound calls are sent from Mastercard to an endpoint exposed by you to notify you of transactions that occurred on the user's cards. Your webhook endpoint must support HTTPS POST requests that receive JSON payloads. If you already have SSL certificates issued by an external certification authority for your endpoints, you will need to provide those details as part of your integration to validate if it is supported by Mastercard. Below is the list of Mastercard-supported CAs: ```cmd 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=ValFac MasterCard Identity Check Root CA,OU=MasterCard Identity Check Gen 3,O=MasterCard,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 ```
Also add the Entrust root certificate to your server trust store: [Entrust L1k Root Cert](https://web.entrust.com/root-certificates/entrust_l1k.cer) To secure your webhook endpoint, you may want to whitelist the Mastercard Outbound NAT addresses. You can also implement an MTLS check. Contact [transaction.notifications@mastercard.com](mailto:transaction.notifications@mastercard.com) for IP details and client certificates. ## Payload Decryption {#payload-decryption} By default, transaction notifications do not contain any sensitive data. The notification payload is delivered as a plain text JSON object. However, if you are configured to receive sensitive data (for example, PAN or expiry) in transaction notifications, Mastercard encrypts the notification payload during transmission. Transaction Notifications uses [JSON Web Encryption (JWE)](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/) to encrypt the payload. Example encrypted JSON payload: ```json { "encryptedValue": "eyJraWQiOiI3NjFiMDAzYzFlYWRlM(...)==.Y+oPYKZEMTKyYcSIVEgtQw==" } ``` Mastercard provides [client encryption libraries](https://github.com/Mastercard?q=client-encryption) in several languages you can integrate into your project or use as a reference to decrypt the payload. Example of decryption using Java client library: ```java JweConfig config = JweConfigBuilder.aJweEncryptionConfig() .withDecryptionKey(privateKey) .withDecryptionPath("$.encryptedValue", "$") .withEncryptedValueFieldName("encryptedValue") .build(); return JweEncryption.decryptPayload(encryptedPayload, config); ``` ## How to Consume the API? {#how-to-consume-the-api} There are two ways of integrating with Transaction Notifications: * [Generating your Own Transaction Notifications API Client](https://developer.mastercard.com/transaction-notifications/documentation/api-basics/index.md#generating-your-own-transaction-notifications-api-client) * [Using a Method Of Your Choice](https://developer.mastercard.com/transaction-notifications/documentation/api-basics/index.md#using-a-method-of-your-choice) ### Generating your Own Transaction Notifications API Client {#generating-your-own-transaction-notifications-api-client} Create customizable API clients from the Transaction Notifications API specification and let Mastercard open-source client libraries handle the authentication for you. This approach offers more flexibility and is strongly recommended. To generate a client, follow our [Generating and Configuring a Mastercard API Client](https://developer.mastercard.com/platform/documentation/developer-tools/generating-and-configuring-a-mastercard-api-client/) tutorial with the following API specification: [inbound.yaml](https://static.developer.mastercard.com/content/transaction-notifications/swagger/inbound.yaml) (24KB) ### Using a Method of Your Choice {#using-a-method-of-your-choice} Transaction Notifications exposes a REST API: you are free to use the REST/HTTP client of your choice and can still 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. For that, refer to the Transaction Notifications [REST API Reference](https://developer.mastercard.com/transaction-notifications/documentation/api-reference/index.md). ## Environments {#environments} | Environment | Base URL | Description | |:------------|:----------------------------------------------|:----------------------------------------------------------------------------------------------------------| | Sandbox | `https://sandbox.api.mastercard.com/openapis` | Free sandbox package where you can enroll test cards and receive test transactions with standard payload. | | Production | `https://api.mastercard.com/openapis` | Production environment for Trial and Commercial tiers. | For more information, refer to [Available Plans](https://developer.mastercard.com/transaction-notifications/documentation/plans/index.md). ## Headers {#headers} The only required header, apart from `Authorization`, is `Content-Type` which must be `application/json`. ## Next Steps {#next-steps} To get started, see the [Quick Start Guide](https://developer.mastercard.com/transaction-notifications/documentation/quick-start-guide/index.md).