# Notifications
source: https://developer.mastercard.com/commercial-event-notifications/documentation/parameters/notifications/notifications/index.md

The Commercial Event Notifications API issues near real-time notifications with details of virtual card number (VCN) [supported events](https://developer.mastercard.com/commercial-event-notifications/documentation/index.md#Overview).

## Notification Delivery Modes {#notification-delivery-modes}

Once you have created a subscription, you can retrieve resulting notifications using either **push** or **pull** mode, or you can use a combination of both as suits your business processes.
For push mode, if you have registered a push endpoint (also known as a callback or webhook URL) during service onboarding, notifications are queued for delivery to this URL as soon as they are created.
They are also stored in the notification store for a period of time following their generation.

Whether or not you are using push mode, you can use pull mode to retrieve notifications from the store by making HTTP GET calls to the /notifications resource.

Use the push approach as the primary way to retrieve notifications. You can then use the pull approach to retrieve notifications that were generated but were not be delivered through push, for example if your server that processes the push notification fails.
Note: Notifications are retained for a period of time following their generation, so you can retrieve them if your notification processing system was not available. Currently, notifications are retained for seven days from the time they were created. This period is subject to change. Any change to this retention period will be advised ahead of time.

## Handling Delayed or Unavailable Notifications {#handling-delayed-or-unavailable-notifications}

If there is a high volume of any [supported event](https://developer.mastercard.com/commercial-event-notifications/documentation/index.md#Overview) occurring, notifications delivery might be transiently delayed. Also, in certain situations, a notification might not be generated for a matching event. This does not affect the authorization, clearing and settlement of that transaction and corresponding authorization/clearing records are available through ICCP authorization/clearing reports or Business Payment Controls authorization/clearing reports. Design your business process to handle these situations.

## Push Notifications {#push-notifications}

Stand up a server at the path registered during the onboarding process to receive notifications. The API pushes the notifications using an HTTP POST request to that path as soon as the notifications are created. For an efficient delivery, the API combines multiple notifications (from the same or different subscriptions) together in a single request.
Note:   

* There is a slight possibility that the same notification might be delivered more than once. Take steps in your application to check unique information in the notification content to prevent processing the same notification multiple times.
* While Commercial Event Notifications delivers notifications in near-real time after Mastercard receives and processes the associated event, upstream event submission timing may vary depending on network, acquirer, processor, or merchant behavior. In particular, clearing events may occasionally be submitted and processed in batch-based models, which can impact notification timing.

### Security {#security}

Outbound calls are sent from Mastercard to an endpoint exposed by you to notify you of events that happened on the user's virtual cards.  

The defined endpoint needs to be capable of receiving an `HTTPS POST` of JSON data. You must also support the TLS/mTLS authentication protocol. You will also need to add a DigiCert root certificate into your sever trust store:  

* Root CA: [DigiCert Assured ID Root G2](https://www.digicert.com/kb/digicert-root-certificates.htm#roots:~:text=expired%20%C2%A0%C2%A0revoked-,DigiCert%20Assured%20ID%20Root%20G2,-Download%20PEM%20%7C)
* Sub CA: [DigiCert Assured ID Client CA G2](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)

## GET /notifications {#get-notifications}

Retrieves notifications created between a specific time range for all subscriptions. You can also retrieve notifications for specific subscriptions and paginate the response using offset and limit parameters.
By default, this endpoint returns the notifications in the ascending order with the oldest notifications returned first.

With reference to the OAS3 (Swagger) definition of this API, notifications are delivered using a hierarchical JSON structure as follows:

* Each `BPC_PAYMENT_AUTHORIZATION` notification is contained in a notification object, which in turn contains metadata about the notification and a *BPCAuthorizationNotificationContent* object.
* Each `BPC_CLEARING notification` is contained in a notification object, which in turn contains metadata about the notification and a *BPCClearingNotificationContent* object.
* Each `PAYMENT_AUTHORIZATION` notification is contained in a notification object, which in turn contains metadata about the notification and a *ICCPAuthorizationNotificationContent* object.
* Each `PAYMENT_UPDATE notification` is contained in a notification object, which in turn contains metadata about the notification and a *BPSPaymentUpdateNotificationContent* object.
* Each `CLEARING` notification is contained in a notification object, which in turn contains metadata about the notification and a *ICCPClearingNotificationContent* object.
* Each `TOKEN_LIFECYCLE_EVENT` notification is contained in a notification object, which in turn contains metadata about the notification and a *ICMPLifeCycleNotificationContent* object.
* Each `TOKEN_PROVISIONING_EVENT` notification is contained in a notification object, which in turn contains metadata about the notification and a *ICMPProvisioningNotificationContent* object.
* The push notification payload, which is the request body in an HTTP POST to the push endpoint, consists of an array of notification objects.
* The pull notification payload, which is the body of a response to a GET request, contains the array of notification objects wrapped in a *NotificationsWrapper* object. This wrapper contains pagination fields to assist clients when fetching a large number of notifications.

### Try it Out {#try-it-out}


API Reference: `GET /notifications`