# Support source: https://developer.mastercard.com/transaction-notifications/documentation/support/index.md ## FAQ {#faq} ### TRANSACTION NOTIFICATION FAQS {#transaction-notification-faqs} No, Mastercard has options for both PCI compliant and non PCI compliant partners. However, if you would like to handle the PAN number of the cardholder, PCI compliance is necessary. If you no longer wish to receive transaction notifications for certain card(s), please utilize the [Delete Consent APIs](https://developer.mastercard.com/consent-management/documentation/api-reference/#delete-consents). Our offboarding process is designed to be smooth and convenient. Please reach out to us at [transaction.notifications@mastercard.com](mailto:transaction.notifications@mastercard.com), and we will be happy to guide you through the process. Transaction Notifications Service is currently running with a select few customers. To join the waitlist for access to the Production environment, fill out the Transaction Notifications Product Interest Form in the [overview](https://developer.mastercard.com/transaction-notifications/documentation/index.md#tiered-access) section. We will then contact you when you are eligible for product access. While the duration to keep undelivered transactions is configurable, it is 7 days by default. After the set duration has passed, the undelivered transactions will be deleted from the system. The undelivered-notifications endpoint includes parameter called **after** , which is the start sequence number of undelivered notifications. For the first call, nothing needs to be set for the **after** parameter and it will return the first 100 notifications and the *nextCursor* value in the response. In subsequent calls, you need to pass the *nextCursor* value in the after query parameter. If no value is passed, it will fetch the oldest events stored in the system. should keep track of the *nextCursor* value. This is especially valuable if there are more than two outages within the set duration and the user does not want to retrieve the same messages. Your response code should be either 200 or 201, any other response code will be treated as failure and we will attempt to send the notification again (retry) at different intervals for up to 24 hours. After that, the failed transaction notification will be stored in the system and the customer can get details using the undelivered-notifications API. * You can designate your webhook URL to be setup during your onboarding for MTF and PROD. We recommend providing your webhook URLs early in the project to avoid any unnecessary delays due to the webhook configuration process. Please note that this feature is not available in the sandbox testing (free tier). * Once onboarded, contact the Transaction Notifications team to change the URL. * Below are the authorization network messages that we support: #### Message Types {#message-types} | **Message Type** | **Description** | |-------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **AUTH_RESPONSE** | Authorization response | | **AUTH_ADVICE** | The Authorization Advice/0120---Acquirer-generated message advises of an authorization that was carried out on the issuer's behalf. | | **REVERSAL_REQUEST** | Reversal request | | **REVERSAL_ADVICE** | The Reversal Advice/0420 message fully reverses a previous Authorization Request/0100. It advises an issuer of a Reversal Request/0400 responded to by the Authorization Platform. | | **DEBIT_AUTH_RESPONSE** | Financial transaction request response | | **DEBIT_AUTH_ADVICE** | Financial transaction advice | | **DEBIT_ACQ_REVERSAL_ADVICE** | Acquirer reversal advice | | **DEBIT_ISS_REVERSAL_ADVICE** | Issuer reversal advice | | **EXT_AUTH_ADVICE** | Acquirer generated authorization response | * If you'd like to limit the types of authorization messages your service is receiving through Transaction Notifications, a filter can be set during your onboarding to remove any auth messages that aren't relevant to your service. ### DATA ELEMENTS FAQS {#data-elements-faqs} Yes, TNS supports the authorization code, which is configured as DE 38 in the ISO message of the authorization response. However, as part of our data minimization principles, we do not send this data by default to all our partners. If you require this data for your specific use case, we can enable sending the authorization code in notifications. No, acquirerID and acquirerICA are different. No both fields are different. **transactionLocalDate** and **transactionLocalTime** - refers to local month and day on which the transaction takes place at the point of card acceptor(merchant) location and is configured in DE13 in ISO message (Timezone details are not provided. If require , client can derive based on merchant's location). **transmissionDate** and **transmissionTime** - refers to the date and time that a message is entered into the Mastercard Network. Date/Time is expressed in Coordinated Universal Time (UTC) and is configured as DE7 in ISO message. This time is used to track different messages such as authorization, file update, administrative, network management. The **systemDateTime** is related to the notification delivery date/time set by the Open API server. The standard transaction notification will include a default transaction payload of data elements. You can request additional data elements from the table below. We will evaluate your request and use case for applicability prior to onboarding. #### Data Elements {#data-elements} | Data element | Name | Description | |:-------------|:-----------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **DE 2** | **Primary Account Number (PAN)** | A series of digits used to identify a customer account or relationship, up to 19 digits long and conforming to ISO 7812 and ISO 7813 specifications. It consists of three primary components: i) Issuing Institution Information (IIN) ii) Individual Account ID Number iii) PAN check digit. | | **DE 3** | **Processing Code** | Describes the effect of a transaction on the customer account and the type of accounts affected. Examples of effects can be: a purchase, a withdrawal, a cash disbursement, a deposit, a refund, a a check deposit, an account balance inquiry, an account transfer a PIN unlock or a PIN change, etc. Examples of type of accounts can be: a savings account, a checking account, a credit card account, a corporate account, a stored value account, a revolving loan account, etc. | | **DE 4** | **Amount, Transaction** | Amount of funds the cardholder requested in the local currency of the acquirer or source location of the transaction. | | **DE 5** | **Amount, Settlement** | Amount of funds to be transferred between the acquirer and the issuer equal to the transaction amount (DE 4) in the settlement currency. Mastercard programs and services use U.S. dollars as the currency of settlement. | | **DE 6** | **Amount, Cardholder Billing** | Transaction amount in the issuer's currency. It is the amount billed to the cardholder in the cardholder account currency, excluding cardholder billing fees. | | **DE 7** | **Transmission Date and Time** | Date and time that a message is entered into the Mastercard Network. | | **DE 9** | **Conversion Rate, Settlement** | Factor used in the conversion from transaction to settlement amount. The transaction amount (DE 4) is multiplied by the settlement conversion rate (DE 9) to determine the settlement amount (DE 5). | | **DE 10** | **Conversion Rate, Cardholder Billing** | Factor used in the conversion from transaction to cardholder billing amount. The transaction amount (DE 4) is multiplied by the cardholder billing conversion rate (DE 10) to determine the cardholder billing amount (DE 6). | | **DE 11** | **Systems Trace Audit Number** | A number a message initiator assigns to uniquely identify a transaction. Must remain unchanged for all messages associated with a given system transaction, which includes all responses and acknowledgements related to an original request message. | | **DE 12** | **Time, Local Transaction** | Local time at which the transaction takes place at the point of card acceptor location. | | **DE 13** | **Date, Local Transaction** | Local month and day on which the transaction takes place at the point of card acceptor location. | | **DE 14** | **Date, Expiration** | Year and month after which an issuer designates a cardholder's card to be expired. | | **DE 15** | **Date, Settlement** | Date (month and day) that funds will be transferred between an acquirer and an issuer or an appropriate intermediate network facility (INF). | | **DE 16** | **Date, Conversion** | Effective date of settlement conversion rate (DE 9) and also the cardholder billing conversion rate (DE 10). | | **DE 18** | **Merchant Type** | Classification (card acceptor business code/merchant category code \[MCC\]) of the merchant's type of business or service. All codes can be found in this MCC Listing spreadsheet, which also includes the domestic country-specific codes. Comprehensive documentation can be found in the [Quick Reference Booklet](https://www.mastercard.us/content/dam/public/mastercardcom/na/global-site/documents/quick-reference-booklet-merchant.pdf) | | **DE 20** | **Primary Account Number (PAN) Country Code** | Code identifying the country where the card issuer is located. All values can be found in the [Quick Reference Booklet](https://www.mastercardconnect.com/-/sign-in?MCCRedirectTo=https://w204.mastercardconnect.com%2FFIMIDP%2Fsps%2Fauth) | | **DE 22** | **Point of Service Entry Mode** | Method used for PAN entry to initiate a transaction and the PIN entry capabilities. Examples of PAN entry modes can be: PAN manual entry, PAN auto-entry via magnetic stripe, via bar code reader, optical character reader, .chip, contactless M/Chip, PAN/token entry via electronic commerce containing a cryptogram, credential on file, etc. Examples of PIN entry modes can be: terminal has or does not have PIN entry capability, mPOS software-based PIN entry capability. | | **DE 23** | **Card Sequence Number** | Distinguishes among separate cards having the same Primary Account Number. | | **DE 26** | **Point of Service (POS) PIN Capture Code** | Maximum number of PIN characters that the acquiring terminal device is capable of accepting. | | **DE 28** | **Amount, Transaction Fee** | Fee charged whenever an online transaction fee is permitted by the operating rules of a bank card product, for transaction activity as a debit or a credit of the Acquirer (and inversely of the Issuer) and expressed in the currency of the transaction amount (DE 4). | | **DE 32** | **Acquiring Institution Identification Code** | Mastercard customer ID number that Mastercard assigned to the entity acting as the acquiring institution for a transaction. | | **DE 33** | **Forwarding Institution Identification Code** | When an institution acts as the customer processing system (CPS) or intermediate network facility (INF) for an acquirer, Mastercard customer ID number of the CPS or INF responsible for directly routing that message to the Authorization Platform. | | **DE 35** | **Track 2 Data** | Information encoded on track 2 of the card magnetic stripe as defined in the ISO 7813 specification. For chip transactions, carries data read from the chip as EMV tag 57 (Track 2 Equivalent Data). It includes the Primary Account Number (PAN), the expiration date and a service code. The service code provides information on card capability.. For example whether the card can be used internationally or for national use only, whether it's a private label card, a proprietary card, whether positive online authorization is required, whether PIN is required, etc. Track 2 data content and format can be found in the [Security Rules and Procedures](https://www.mastercardconnect.com/-/sign-in?MCCRedirectTo=https://w204.mastercardconnect.com%2FFIMIDP%2Fsps%2Fauth). The service code values can be found in the same [document](https://www.mastercardconnect.com/-/sign-in?MCCRedirectTo=https://w204.mastercardconnect.com%2FFIMIDP%2Fsps%2Fauth) | | **DE 37** | **Retrieval Reference Number** | Document reference number assigned by the acquirer used by automated merchant POS systems as a unique receipt or sales document identifier to satisfy regulatory or legal requirements. For chip transactions it consists in the date the transaction is captured at the point-of-service terminal, initiator discretionary data and a terminal transaction number. | | **DE 38** | **Authorization Identification Response** | Card Issuer-generated authorization code for authorization transactions. It can include an Account Level Management account category code. | | **DE 39** | **Response Code** | Defines the disposition of a previous message or an action taken as a result of receipt of a previous message. also are used to indicate approval or decline of a transaction. In the event an authorization is declined, the response code indicates the reason for rejection. Examples of reason can be invalid card number, expired card, invalid PIN, stolen card, insufficient funds/over credit limit, etc. The response code may indicate an action to be taken at the card acceptor. For example, the capture of a card. | | **DE 41** | **Card Acceptor Terminal Identification** | Identifier assigned by the terminal owner to a terminal at the card acceptor location of acquiring institutions or merchant POS systems. Unique value within the terminal owning organization. | | **DE 42** | **Card Acceptor Identification Code** | Identifies the card acceptor that defines the point of the transaction in both local and interchange environments. Used as a merchant ID assigned by the acquirer to uniquely identify the merchant in a POS transaction. | | **DE 43** | **Card Acceptor Name and Location** | Name and location of the card acceptor that defines the point of interaction in both local and interchange environments. | | **DE 44** | **Additional Response Data** | Contains supplemental data depending on the program or service. For example, it can provide the phone number of the Issuer to call, a cardholder ID number, a cardholder's last name, indication of invalid information provided in the case of corporate fleet card transactions, error codes, etc. | | **DE 45** | **Track 1 Data** | Information encoded on track 1 of the card's magnetic stripe as defined in the ISO 7813 specification. It includes the Primary Account Number (PAN), the cardholder name, the expiration date and a service code. The service code provides information on card capability.. For example whether the card can be used internationally or for national use only, whether it's a private label card, a proprietary card, whether positive online authorization is required, whether PIN is required, etc. Track 2 data content and format can be found in the [Security Rules and Procedures](https://www.mastercardconnect.com/-/sign-in?MCCRedirectTo=https://w204.mastercardconnect.com%2FFIMIDP%2Fsps%2Fauth). The service code values can be found in the same [document](https://www.mastercardconnect.com/-/sign-in?MCCRedirectTo=https://w204.mastercardconnect.com%2FFIMIDP%2Fsps%2Fauth). | | **DE 48** | **Transaction Category Code** | Classifies major categories of transactions. Examples can be: automobile/vehicle rental, manual cash disbursement, restaurant, hotel/motel, hospital, college/school expense, payment transaction that transfers funds to a cardholder account, U.S. POST exchange, cardholder-activated magnetic stripe-reading terminal, non-face-to-face transactions, airline, railroad, travel agency/transportation, automated cash disbursement. All possible values are documented in the [Quick Reference Booklet](https://www.mastercard.us/content/dam/public/mastercardcom/na/global-site/documents/quick-reference-booklet-merchant.pdf) | | **DE 49** | **Currency Code, Transaction** | Local currency of the acquirer or source location of the transaction. | | **DE 50** | **Currency Code, Settlement** | The currency of the settlement amount (DE 5) and the actual replacement settlement amount (DE 95). All Mastercard programs and services use U.S. dollars (840) as the currency of settlement for programs and services that the Authorization Platform supports. | | **DE 51** | **Currency Code, Cardholder Billing** | The currency of the cardholder billing amount (DE 6) and the actual replacement cardholder billing amount (DE 95). | | **DE 54** | **Additional Amounts** | Information on up to two amount types and related account data. Examples of amount type: ledger balance, available balance, amount owing, amount due, healthcare eligibility amount, prescription eligibility amount, vision Rx eligibility amount, Mastercard prepaid online bill pay transaction fee amount, amount cash back, amount gratuity, original amount, POI amount, limit/balance available amount from Mastercard In Control. These amount types can be used in different contexts, that are partial approval, account balance for prepaid accounts and in ATM transactions, purchase with cash back, cash back without purchase, real-time substantiation, purchase of goods or services without cash back, POI currency conversion (aka dynamic currency conversion). | | **DE 60** | **Advice Reason Code** | Can indicate Automated Fuel Dispenser Completion. message processing information, e.g. no response from issuer, and product-specific information. | | **DE 61** | **Point of Service (POS) Data** | Conditions that exist at the point of service at the time of the transaction. Namely if the card acceptor is attending the terminal, the terminal location, whether the cardholder is present at the point of service, the card's presence at the point of service, whether the terminal has card capture capabilities, the purpose or status of the request, the card acceptor's confidence in the transaction security level, the type of cardholder-activated terminal used by the cardholder to initiate the transaction, the set of methods supported by the terminal for the input of account number, card, or mobile device data, the country of the POS location, the postal code of merchant location. Possible values are documented in the [Customer Interface Specification](https://www.mastercardconnect.com/-/sign-in?MCCRedirectTo=https://w204.mastercardconnect.com%2FFIMIDP%2Fsps%2Fauth). | | **DE 62** | **Intermediate Network Facility (INF) Data** | INF network trace information that allows acquiring INFs to directly route the chargeback or retrieval request to the original acquirer without the requirement of maintaining large online reference databases containing the original transactions. | | **DE 63** | **Network Data** | Identifies the specific program or service (for example, the financial network, financial program, or card program) with which the transaction is associated. It includes the financial network code (aka product code) and the banknet reference number which is guaranteed to be a unique value for any transaction within the specified financial network on any processing day. | | **DE 95** | **Replacement Amounts** | Amounts necessary to perform a partial or full reversal of a financial transaction: the actual transaction amount. the actual settlement amount in the settlement currency, and the actual amount in the issuer currency. | | **DE 102** | **Account Identification-1** | Identifies the 'from' customer account in a transfer transaction. | | **DE 103** | **Account Identification--2** | Identifies the 'to' customer account in a transfer transaction. | | **DE 104** | **Digital Payment Data** | Digital payment data for ecommerce transactions: the estimated purchase amount of the transaction when the payment request is presented to the consumer during checkout, a merchant identifier such as the merchant business website URL or reverse domain name as presented to the consumer during checkout, the digital service provider and the digital authentication data. | | **DE 108** | **Additional Transaction Reference Data** | Sender, receiver, and transaction level data for Mastercard Send Transactions (Funding Transactions, MoneySend Payment Transactions, and Gaming and Gambling Payments Transactions), and Mastercard Merchant Presented QR Transactions. | | **DE 120** | **Record Data** | Address verification service data, which includes the cardholder postal/ZIP code and address. | | **DE 123** | **Mastercard Merchant Data Services** | Mastercard-cleansed merchant data: address, postal code, country code, telephone number, legal corporate name, URL. | | **DE 124** | **Member-defined Data** | Contains supplemental data depending on the program or service. For example, it can provide the PAN source which is the method by which the cardholder is attempting to tokenize a PAN, the wallet provider account ID hash which is typically a cardholder email hash, cardholder name, device source IP address, device location, mobile number last 4 digits. | The test card (\*\*\*\*1066) is the common test card in Mastercard and being widely used by other Mastercard teams for their testing to create the transactions in the Mastercard switch. If you have enrolled this card, you will receive notifications for all the transactions for the test card. | Term | Description | |:-----------------------|:----------------------------------------------------------------------------------------------------------------------| | **Transaction Amount** | Amount of funds the cardholder requested in the local currency of the acquirer or source location of the transaction. | | **Cardholder Amount** | Amount of funds requested as shown in the bank statement. | #### Examples: {#examples} ##### Here are two cross-border examples: {#here-are-two-cross-border-examples} 1. A US cardholder goes to Italy and buys a wallet priced at 15 Euros and selects Euros as the payment amount: * transactionAmount will be 1500 with EUR as the transactionCurrency * cardholderAmount will be 1672 in USD as the cardholderCurrency 2. A US cardholder goes to Italy and buys a wallet priced at 15 Euros and selects USD as the payment amount presented as 1692 on the POS: * transactionAmount will be 1692 with USD as the transactionCurrency * cardholderAmount will be 1692 in USD as the cardholderCurrency Refer to the [API specifications](https://developer.mastercard.com/transaction-notifications/documentation/api-reference/endpoints/index.md#openapi-specification) * 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 notification delivery. If you respond to notification delivery with a validation error, it will result in notification delivery failure. Upon failure, the same notification will be retried by the retry mechanism, creating duplicate notifications. * In certain scenarios, such as connection drops or timeouts, our system's retry logic may result in duplicate transaction notifications. To handle and remove these duplicates, you can implement a deduplication strategy using a combination of the following elements from notification payload: Card Reference, Transmission DateTime, Financial Network Code, and BankNet. This method will help you efficiently manage and eliminate duplicate notifications on your end. ### AUTHORIZATION \& TRANSACTION LIFECYCLE FAQS {#authorization--transaction-lifecycle-faqs} Yes, it is possible to link different notifications for the same transactions. * There can be clearing without authorization and there can be an authorization without clearing. * A transaction isn't finalized until it has been cleared which is usually, but not always, preceded by an authorization message. Cleared transactions that are switched outside of the Mastercard Network will not receive an authorization notification. * When there is an auth with no clearing - for example, an authorization can be an Account Status Inquiry check to ensure the card is in good standing before a transaction is intended to take place or for a card on file. * More information and filters can be put in place during onboarding to ensure you are only getting the data you need for your service. To ensure persistence in notification delivery, we have implemented a retry feature for delivering transaction notifications. During the notification delivery, we expect the client to send an HTTP 2XX response back as soon as they receive the transaction notification on their configured webhook endpoint. Any HTTP response other than a 2XX response code will be marked as a notification delivery 'failed.' If the notification delivery fails, we attempt to redeliver the transaction notification at certain intervals until it succeeds or 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. ### CLEARING API FAQS {#clearing-api-faqs} A transaction usually clears within 5 days. 95%+ of transactions will be available within this time frame via the Clearing API. Some examples of transactions that might clear past 5 days are online orders in which the processor only clears a transaction after the item is shipped. Yes. An example of this is an airline transaction where one person purchases multiple tickets in one transaction. Depending on the airline, each ticket might clear as a new clearing record, resulting in multiple clearing records for one auth transaction. When the "transactionType" is "20", this signifies a credit back to the account. There are two ways to receive clearing data. One way is to receive data via webhooks. The other is to pull the data via a GET API call. Clearing data for your service will only be available once you have been approved for the service. Please check the IPM Clearing Formats manual to see all the data elements that are available via clearing. Any additional data elements in addition to the default will need approval from the Transaction Notifications team to become available. Clearing data via our APIs is currently unavailable for smart data enabled cards. If you want to receive clearing records for these smart data enabled cards, we recommend you implement CDF3 files with the commercial solutions team. Please reach out to our email for further clarification on this. ## Get Help {#get-help} Email us at [transaction.notifications@mastercard.com](mailto:transaction.notifications@mastercard.com) with any further questions. Transaction Notification Service is currently running with a select few customers, to request access to Production environment please contact us at [transaction.notifications@mastercard.com](mailto:transaction.notifications@mastercard.com).