# Transaction Notifications Webhook source: https://developer.mastercard.com/transaction-notifications/documentation/api-reference/transaction-notification-webhook/index.md ## Overview {#overview} When the cardholder makes a purchase, you will receive a real-time notification on your Transaction Notifications Endpoint (Webhook URL). The notification contains the card reference, amount, merchant details and the issuer decision (approval/decline). You can then decide how to use the notification depending on your use case. ## Security {#security} Outbound calls are sent from Mastercard to an endpoint exposed by you to notify you of transactions that happened on the user's cards. The defined endpoint needs to be capable of receiving an HTTPS POST of JSON data. You must also support the MSSL (mutual SSL/TLS authentication) protocol. 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: 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
You will also need to add entrust root certificate into your sever trust store: Entrust [L1k Root Cert](https://web.entrust.com/root-certificates/entrust_l1k.cer) ## Securing your webhook endpoint {#securing-your-webhook-endpoint} To secure your transaction notifications end point, you may want to whitelist the Mastercard Outbound NAT Addresses. In addition, you can also implement MTLS check. Please contact [transaction.notifications@mastercard.com](mailto:transaction.notifications@mastercard.com) for IP details \& client certificates. ## How It Works {#how-it-works} Diagram usertransaction 1. Cardholder makes a purchase at some merchant. 2. Mastercard Authorization Network receives the transaction. 3. Mastercard forwards the filtered purchase data to your service. In real-time, Mastercard will forward the transaction to your endpoint URL. The notification contains the card reference, amount, merchant details and the issuer decision (approval/decline). For a full list of notification data elements please check the [OpenAPI Specification](https://developer.mastercard.com/transaction-notifications/documentation/api-reference/transaction-notification-webhook/index.md#openapi-specification) below. 4. You receive the notification containing the card reference to the enrolled webhook endpoint. 5. You may optionally perform a communication to the cardholder by notifying the cardholder of the purchase. It is up to you to decide the cardholder communication.
## OpenAPI Specification {#openapi-specification} API Specification: `https://static.developer.mastercard.com/content/transaction-notifications/swagger/outbound.yaml`
## Payload Decryption {#payload-decryption} By default, transaction notifications don't contain any sensitive data. Hence, the transaction notification payload will be delivered as a plain text JSON object. However, in some cases where the client is configured to receive sensitive data (e.g., PAN, expiry, etc.) in transaction notifications, we encrypt the transaction notification payload during transmission over the network. Transaction Notification service utilizes [JSON Web Encryption (JWE)](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/) to encrypt the payload. Here is an example of 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 to your project or use as reference to decrypt the payload. An example of decryption using Java client library: ```java JweConfig config = JweConfigBuilder.aJweEncryptionConfig() .withDecryptionKey(privateKey) .withDecryptionPath("$.encryptedValue", "$") .withEncryptedValueFieldName("encryptedValue") .build(); return JweEncryption.decryptPayload(encryptedPayload, config); ``` ## Notification Delivery Persistence and Retry Mechanism {#notification-delivery-persistence-and-retry-mechanism} In circumstances where a transaction notification may have failed to deliver to your webhook endpoint, we have implemented a retry mechanism to ensure the delivery of transaction notifications. When there has been a successful transaction notification delivered, our system anticipates your service to send an HTTP 2XX response back as soon as they receive the transaction notification on their configured webhook endpoint. If we receive any HTTP response other than a 2XX response code, the transaction notification will be marked with a 'failed' delivery. If the notification delivery fails, we attempt to redeliver the transaction notification at certain intervals until it succeeds for a maximum of 24 hours. After 24 hours, if we are still unable to successfully deliver the notification, we save these failed notifications in our system. These failed and saved transaction notifications can be retrieved by calling the 'undelivered-notifications' API. In order to ensure that there is proper communication between our systems and we are not falsely retrying to deliver the notification, notification delivery must be acknowledged instantly upon the receipt of the notification payload. We do not recommend performing any data field validation before responding to the notification webhook. Validation should be done on a separate thread and should not affect the response of the transaction notification delivery. If you respond to the delivery with a validation error, it will result in a failed transaction notification delivery. If you have further questions regarding transaction notification data, please refer to the FAQ section. ## Handling Duplicate Transaction Notifications {#handling-duplicate-transaction-notifications} In certain situations, such as connection drops or timeouts, our system's retry mechanism may occasionally generate duplicate transaction notifications. To manage and eliminate these duplicates for: * **Authorization Notifications** : Use the `transUid` field in the notification payload, which is unique for each authorization notification. * **Clearing Notifications** : Use the `clearingUniqueId` field, which is unique for each clearing notification. Implementing this approach will help you effectively handle duplicate notifications. ## Multiple webhooks support {#multiple-webhooks-support} If you have any specific requirement to separate the webhooks per market region or per use case, Transaction notifications APIs can support multiple webhooks. To enable multiple webhooks, while onboarding webhook URLs at mastercard end, we will create the webhook selector assigned to each URL. For instance, if your user base spans Europe and the US, and you maintain separate servers for each region, you may want to receive transaction notifications on distinct webhooks for EU and US users. To support this, during onboarding each webhook URL is associated with a unique webhook selector: | Webhook Endpoint | Webhook Selector | |:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------| | | FINTECH-US | | | FINTECH-EU | | | | | These webhook selectors are then utilized when enrolling cardholders using consent APIs. If you're using consent APIs to enrol the card holders, you can specify the webhook selector in the create consent request. For example, when creating consent for a US cardholder to receive notifications on your US endpoint: | | ```json  { "consents": [ { "name": "notification", "details": {"webhookSelector": "FINTECH-US","businessName": "BusinessA"} } ], "cardDetails": { ... } } ``` If you are using Mastercard UI for card enrolment, webhook selector should be passed in JWT payload as below: ```json  JWT Payload: { "exp": 1583760792, "iat": 1583758992, "jti": "cb", "nbf": 1583758992, "appdata": { "callbackURL": https://fintech.com, "consents": [ { "name": "notification", "details": {"webhookSelector": "FINTECH-US","businessName": "BusinessA"} ... } } } ``` In bulk API case, ```json  { "cards": [ { "accountNumber": "511XXXXXXXXXX444", "recId": "R1", "expiry": "01/2027" } ], "consents": { "notification": { "webhookSelector": "FINTECH-US", "businessName": "BusinessA" ... } } } ``` Based on the webhook selector provided during enrollment, transaction notifications will be directed to the corresponding webhook endpoint.