# Auth Notifier source: https://developer.mastercard.com/pay-with-rewards/documentation/use-cases/auth-notifier/index.md Note: The following documentation pertains to both Pay with Rewards(PwR) and Card Linked Services(CLS) The Auth Notifier offers the capability to send an outbound notification after its engine evaluates a transaction, more specifically, an authorization. The Auth Notifier provides the processing result of a Pay with Rewards transaction and is therefore useful for real-time user notifications (email, SMS, in-app notification) and other uses (redeeming points, applying a rebate, logging analytics information). ## Using the Auth Notifier {#using-the-auth-notifier} ### Supported Authentication Models {#supported-authentication-models} Certificate Based Authentication w/External API (TLS/mTLS) In establishing an MTLS connection with an outbound application, the Mastercard API Gateway receives a server certificate from the external client, which the API Gateway will validate against a default list of trusted Certificate Authorities (CAs). If the external domain's certificate is signed by one of the trusted CAs, no extra work is needed. OAuth 2.0 In this authentication model, Mastercard's API Gateway acts as a client to authenticate and authorize requests to downstream services using access tokens. We support two types of OAuth 2.0 authentication models 1. OAuth 2.0 Password Grant `grant_type=password` 2. OAuth 2.0 Client Credentials `grant_type=client_credentials` ### Setup and Security {#setup-and-security} In order to use Auth Notifier, you need to provide the following details: 1. Endpoint capable of receiving an HTTPS Post of XML data 2. For MSSL (mutual SSL/TLS authentication) protocol support, SSL server certificates details to Mastercard * Additionally, you should trust the "DigiCert" certification authority and whitelist the below static Mastercard IP addresses. 3. For OAuth 2.0 protocol support * Token endpoint URL * Client ID(If applicable) * Client Secret(If applicable) * Username(If applicable) * Password(If applicable) * Grant Type ##### Mastercard Stage environment {#mastercard-stage-environment} * 12.10.33.240 * 209.64.211.240 ##### Mastercard MTF and Production environments {#mastercard-mtf-and-production-environments} * 12.22.155.240 * 216.119.217.240 * 216.119.209.240 ### Configuration {#configuration} The information that is sent via the Auth Notifier is configurable in two ways: ##### 1. Response codes {#1-response-codes} By default, transactions having the response reason codes 60 and 70 ("success" response codes) are always sent when the Auth Notifier is enabled. Transactions with other response reason codes can also be sent. ##### 2. Data elements {#2-data-elements} Specific data elements related to the transaction can be included. A standard, suggested configuration is provided below ## Additional Information {#additional-information} ### Digital Signature {#digital-signature} The Auth Notification will be an XML message that is signed by Mastercard using standard XML signature methods and is then base64-encoded and sent as a parameter in an HTTPS Post. The HTTPS Post will be sent over a mutually-authenticated connection. The public certificate is included within the request, which you can then use to check the signature, and compare against the known key to determine the message validity. Standard java libraries are used to accomplish this. An example of using java to sign and verify signed xml can be found [here](https://www.oracle.com/technical-resources/articles/java/dig-signature-api.html). XML Digital Signature Methods and Namespace: * Transform: ENVELOPED * Canonicalization Method: EXCLUSIVE * Digest Method: SHA1 * Signature Method: RSA_SHA1 * Default namespace prefix ds * Canonicalization Method namespace ec The HTTPS Post will have the header Content-Type set to text/xml; charset="utf-8" for an XML post. ### Response to the transaction notification {#response-to-the-transaction-notification} Pay with Rewards will be expecting a response to the Post with an HTTP 200 status code. There are no further actions relative to a successful response. The response body can be empty. Any other HTTP status code received is assumed a failure, and a retry would be attempted up to three (3) times only. After three (3) times, the Post will fail and will not be automatically retried. The `` will be of the form "yyyy-MM-ddTHH:mm:ss.SSSSSSSZ". The `` will be of the form yyyy-MM-dd. The `` will be of the form HHmmss. All times in time-zone/Zulu offset is not indicated will be in CST/CDT. Those with Zulu offset are generated by computers in the Central Time Zone and thus have an offset of -5:00 during daylight savings time and -6:00 during standard time. ### Standard Auth Notifier template {#standard-auth-notifier-template} The following list of fields make up the standard Auth Notifier template. The fourth column provides a mapping of each element to the corresponding element in the getAuthorizations API response, if applicable. Note: Work with your account manager(s) if the template needs to be customized Download a sample xml payload here: [Sample_xml_payload.xml](https://static.developer.mastercard.com/content/pay-with-rewards/uploads/Sample_xml_payload.xml) (3KB) | Name | Description | Field Type | Max Length | Example | Corresponding field in getAuthorizations API response | |----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|------------|------------|---------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | AuthResponseLogId | Unique authorization identifier, from MRS | Long | NA | 5295172602 | id | | BanknetRefNum | Reference number generated by the Mastercard authorization source | String | 12 | MPLIP3GXJ | externalId | | TransactionDateTime | Authorization date and time in `yyyy-MM-dd HH:mi:ss` format | String | 19 | yyyy-MM-dd HH:mi:ss | ` de013TransactionDate:de012TransactionTime` | | TransactionTime | Transaction time in HH24miss format. | String | 6 | `HH24miss` | | | TransactionDate | Transaction date in MMdd format. | String | 4 | `MMdd` | | | TransactionAmount | Transaction amount in local currency | String | 12 | 000000001375 | `de004TransactionAmount` | | TransactionAmountFormatted | Formatted transaction amount with currency code symbol | String | 30 | £13.75 | | | MerchantType | Merchant type classification | String | 4 | 5411 | `de018MerchantCode` | | AcquirerId | Acquiring institution identifier | String | 30 | 010495 | `de032AcquiringInstitutionIdCode` | | CardAcceptorId | Identifies the card acceptor. Also, used as a merchant ID to uniquely identify the merchant in a POS transaction | String | 15 | 2101524693 | `de042CardAcceptorIdCode` | | AuthLocation | Name and location of the card acceptor | String | 40 | YOURS SUPERMARKET LEICESTER GBR | `de043CardAcceptorNameLocation` | | TransactionCurrCd | Local currency code of the acquirer | String | 3 | 826 | `de049TransactionCurrencyCode` | | CardholderCurrCd | Customer's billing currency code | String | 3 | 840 | `de051CardholderBillingCurrencyCode` | | ResponseReasonId | Internal MRS reason code assigned to every processed authorization | int | 10 | 60 | responseReasonId | | PointTotal | Point balance of the customer's account | BigDecimal | NA | 2021 | | | AccountId | Internal MRS unique identifier of a customer account | int | 10 | 335098313 | | | CustomerId | Internal MRS unique identifier of a customer | int | 10 | 306175538 | | | PointsToRedeem | Points needed to be redeemed for the purchase, calculated by MRS | BigDecimal | NA | 1375 | pointsRedeemed note: **pointsRedeemed** in the **getAuthorizations** API response is populated only for successfully redeemed purchases and assigned value "0" to eligible and ineligible purchases, whereas **PointsToRedeem** is not tied to whether or not a redemption occurred. | | ProgramId | Program identifier in MRS | int | 10 | 2716 | | | PointConversionFactor | Point to currency conversion rate | BigDecimal | NA | 0.008 | | | BillingAmount | Transaction amount in the issuer's currency | String | 12 | 1375 | `de006CardholderBillingAmount` | | BillingAmountFormatted | Formatted billing amount with issuer's currency code symbol | String | 30 | £13.75 | | | BillingConvRate | Factor used in the conversion from transaction to customer billing amount. DE4 is multiplied by DE10 to determine DE6 | String | 8 | 61000000 | | | ProgramMinThreshold | Minimum (currency) purchase amount for the program | float | NA | | | | ProgramMaxThreshold | Maximum (currency) purchase amount for the program | float | NA | | | | RtrCrdhldrThrdhFromAmt | Minimum threshold amount set by cardholder | float | NA | 0 | | | NonPanToken | Third party loyalty providers will provide their account identifiers on the enrollment. This can be used to call them back when consuming their API | String | 300 | | | | PartialTransactionSw | Indicates if the program allows partial redemption | String | 1 | N | | | PartialTransIncrements | Partial redemption increment | float | NA | 5 | | | ExternalProgramId | External program identifier of non-MRS programs | String | 18 | 8425 | | | CashbackAmount | Cashback amount for successfully redeemed purchases (appears for authorizations with response code 60 only) | BigDecimal | NA | 13.75 | | | RANAC | A Mastercard assigned Random Account Number. This is a Non-PAN identifier that represents a credit card number tied to an account. Optional. | String | 30 | | |