# Push Notifications Details
source: https://developer.mastercard.com/cross-border-services/documentation/api-ref/push-notifications-details/index.md

Mastercard Cross-Border Services offers the following push notifications as opt-in Services:

1. [Status Change Push](https://developer.mastercard.com/cross-border-services/documentation/api-ref/status-change-api/index.md)  
2. [Carded Rate Push](https://developer.mastercard.com/cross-border-services/documentation/api-ref/carded-rate-api/index.md)  
3. [RFI Push](https://developer.mastercard.com/cross-border-services/documentation/api-ref/rfi-apis/notification/index.md)  
4. [Account Validation Push](https://developer.mastercard.com/cross-border-services/documentation/api-ref/account-validation-apis/account-validation-api/index.md)  

Mastercard Cross-Border Services expects HTTP Response Code 200 for all push notifications. In the event of a timeout or error, Mastercard Cross-Border Services will resend the notification with a maximum of three retries. This ould unknowingly cause duplicate notifications. So Mastercard Cross-Border Services recommends Customer to build logic in their systems to identify the `eventRef` and ignore any duplicate notifications with the same `eventRef`.

## Push Notification Setup {#push-notification-setup}

* Push APIs involve a Mutual Secure Connection to be established between Mastercard and the External partner server which exposes the webhook endpoint (URL). This is achieved through Mutual TLS (mTLS) authentication method.

### Step 1: Provide Push API Notification Webhook URL {#step-1-provide-push-api-notification-webhook-url}

You will provide the Webhook URL for both the MTF and the PROD environments. The Webhook URLs must be active on your network.
Mastercard API Gateway (APIGW) does not perform any connectivity check explicitly after onboarding your Webhook. You should confirm your domain is getting pinged from the internet before submitting Webhook URL.

**Follow the below guidelines for the endpoint URL.**

* You should provide endpoint URL.
* The URL needs to be public and reachable on internet.
* It needs to be FQDN (Fully Qualified Domain Name) and HTTPS.
* The domain name should be resolvable and webhook should not be created with IP.
* The URL should end with /Webhook -- no other query parameter in URL or header is allowed/required.   
  Ex: Not accepted: api.fakecompany.com/?id=xxx.   
  Ex: Accepted : api.fakecompany.com/xbs/status/webhook.
* You should not create a webhook expecting Oauth token to be sent.
* You should not create a webhook waiting for a POST parameter containing the api-key (fixed value).
* Mastercard supports different destination paths for push notifications in both mtf and production environments.

Note:   

* Mastercard does not recommend using IP address allow-listing as a security measure for inbound or outbound services. This method is not seen as robust or scalable for securing webhook communications or API integrations.
* However, if your organization needs the list of outbound IP addresses used by the API Gateway for firewall configuration, your Mastercard Customer Implementation Services (CIS) Representative can provide these details upon request.

### Step 2: Exchange certificate {#step-2-exchange-certificate}

#### Configuration Details {#configuration-details}

Note:   

* Use these configuration details only with options 1 and 2 when a Mastercard-issued client certificate is used in the MTLS flow for push notifications.
* For option 3, you must define the Distinguished Name (DN) and Mastercard creates the CSR according to those requirements, as the client certificate will be issued by your Certificate Authority (CA).

Partners and customers using Mastercard products or services via push notifications to partner webhook endpoints should refer to the following certificate Distinguished Name (DN):
* Member-Test-Facility_(MTF)
* Production

```Member-Test-Facility_(MTF)
CN=CrossborderServicesNotification-mtf.mastercard.com, OU=admin, O=MasterCard International Incorporated, L=O'Fallon, ST=Missouri, C=US
```

```Production
CN=CrossborderServicesNotification-prod.mastercard.com, OU=admin, O=MasterCard International Incorporated, L=O'Fallon, ST=Missouri, C=US
```

#### Option 1: CA Trust method for the MTLS {#option-1-ca-trust-method-for-the-mtls}

Mastercard certificate authority (CA) is DigiCert. If you trust all certificates issued by DigiCert as CA, there are no action required by you. In this case, you should already be trusting the DigiCert CA Chain that has signed Mastercard domain certificate.

You can download the outbound DigiCert CA certificates directly from the [CA website](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):

* /C=US/O=DigiCert Inc/CN=DigiCert Assured ID Client CA G2
* /C=US/O=DigiCert Inc/OU=www.digicert.com/CN= DigiCert Assured ID Root G2

Note:   

* If necessary, Mastercard can also share the CA certificates with you through the Key Management Portal in Mastercard Connect.
* As pre-requisite, you must have access to the Key management portal (KMP) in Mastercard Connect and must have registered the KMP security officers through the same application.
* The Inbound and Outbound CA certificates are different. Inbound CA certificates are used for services initiated by the customer to Mastercard, while Outbound CA certificates are used for services initiated by Mastercard to the customer. The DigiCert CA certificates used by Mastercard are:
  * **Inbound**: DigiCert Global G2 TLS RSA SHA256 2020 CA1 and DigiCert Global Root G2
  * **Outbound**: DigiCert Assured ID Client CA G2 and DigiCert Assured ID Root G2 1

#### Option 2: Non-standard MTLS validation {#option-2-non-standard-mtls-validation}

Note: Mastercard recommends using option 1 from the given options for the issued certificate.

A non-standard MTLS validation such as certificate pinning or to locally store the end-entity client certificate for infrastructure requirement, requires Mastercard to share the full CA chain with the customer including the Mastercard client leaf certificate.

1. The CIS implementation representative initiates the request for the key exchange process to the Mastercard Key Management team only after ensuring that the customer can access the KMP portal and can register their KMP security officers.

2. After the key exchange over KMP, you need to download and configure the CA certificates in addition to the Mastercard client certificate in your server trust store for a successful mTLS authentication for outbound services.

3. Follow the instructions [here](https://developer.mastercard.com/cross-border-services/documentation/api-ref/push-api-notification-mtls-setup/index.md) to push the API Notification Mutual TLS setup.

#### Option 3: Third-Party certificates handling process {#option-3-third-party-certificates-handling-process}

If your infrastructure does not support external Certificate Authorities (CAs) like DigiCert for inclusion in your trust store, and instead relies on your own designated CAs to authenticate server connections for outbound communication, then follow these steps for handeling the third-party certificates:

1. Reach out to the Mastercard implementation representative with a request to allow own preferred CAs for authentication.
2. The representative works internally to request handling of the third party client certificates.
3. Once approved, you will get an email from the Key Management team within Mastercard to proceed.
4. Login to KMP and download the CSR.
5. Provide the client certificate signed by your Third-Party CA in the same KMP portal.

<br />

Once the configuration is completed, your Mastercard implementation representative informs you to proceed with the testing phase.

## How to identify {#how-to-identify}

Contact your organization technical team (IT support or operations) that support your servers or APIs that Mastercard connects to and ask them to confirm whether your middleware is configured for the CA Trust method of validating mutually authenticated transport layer security (mTLS) for API's, or if the existing certificates are located in the trust store of your servers.
If your middleware does require end-entity certificates to be stored in the trust store, then add (import) the new previously mentioned certificates into your trust store as additional valid certificates.