Skip to main content
Optimization Protection

Retrieve notifications

In this guide, you will learn how to:

  • Retrieve a notification by ID
  • Retrieve a notification by date range and status

Before you begin

You start receiving notifications after you subscribe to notifications. To retrieve these notifications, you need to either know the notificationId, or the date range or notification status of the required notifications.

Attention
A few things keep in mind:
  • Notifications service may, in rare cases, issue the same notification (with identical data) multiple times due to asynchronous backend processing. It is your responsibility to ensure idempotent handling at your end.
  • A webhook delivery is considered successful when it receives 200 or 201 HTTP code back in response (not for all 2XX). Any other response code is considered as a failed delivery and subsequent measures to resolve the failure will be taken.
  • Webhooks may arrive out of order, so use the webhook’s messageCreateTimestamp field to determine the correct sequence.

Retrieve a specific notification

Retrieve details about a notification by using a GET call to the /notifications/{notificationId} endpoint.

HTTP method: GET
Endpoint: /notifications/{notificationId}

Json
{
    "notificationId": "4444-4017-11e9-b649-8de0642215",
    "merchantId": 9876543210,
    "notificationType": "RecurringProgramNotification",
    "notificationSubType": "PlanUpdated",
    "notificationDescription": "Plan Updated",
    "messageCreateTimestamp": "2020-08-07T09:52:25.686Z",
    "subscriptionId": "3d7e6071-55ea-4e95-b12b-5a79be427b84",
    "callBackUrl": "https://merchant.notification.com",
    "recurringProgramNotification": {
        "planUpdated": {
            "planID": "GH7VoHZHZR",
            "merchantPlanId": "Plan12348",
            "planName": "Gold Plan",
            "planType": "AUTOPAY",
            "planDescription": "Gold Plan Desc",
            "billingFrequencyCount": 1,
            "billingFrequencyUnit": "MONTHS",
            "defaultPlan": true,
            "autoRenewable": false,
            "availableOnCheckout": true,
            "planStatus": "DRAFT",
            "planAmount": 10000,
            "currencyCode": "USD"
        }
    }
}

Retrieve notifications by date and status

You can retrieve notifications by using any of the following filters:

  • Date range (in the format YYYY-MM-DD)

  • Notification status (which could be SENT, FAILED, or PENDING)

  • Both date range and notification status

Retrieve notifications from a specific period by using a GET call to the /notifications endpoint with query parameters indicating the filter applied to the results.

HTTP method: GET
Endpoint: /notifications

Use the following request URL format to apply both date and status filters: notifications?startdate=YYYY-MM-DD&enddate=YYYY-MM-DD&status=SENT

Json
{
    "notificationResponses": [
        {
            "notificationId": "4444-4017-11e9-b649-8de0642215",
            "merchantId": "9876543210",
            "notificationType": "RecurringProgramNotification",
            "notificationSubType": "PlanUpdated",
            "notificationDescription": "PlanUpdated",
            "messageCreateTimestamp": "2020-08-07T09:52:25.686Z",
            "subscriptionId": "3d7e6071-55ea-4e95-b12b-\t5a79be427b84",
            "callbackURL": "https://merchant.notification.com",
            "recurringProgramNotification": {
                "planUpdated": {
                    "planID": "GH7VoHZHZR",
                    "merchantPlanId": "Plan12348",
                    "planName": "Gold Plan",
                    "planType": "AUTOPAY",
                    "planDescription": "Gold Plan Desc",
                    "billingFrequencyCount": 1,
                    "billingFrequencyUnit": "MONTHS",
                    "defaultPlan": true,
                    "autoRenewable": false,
                    "availableOnCheckout": true,
                    "planStatus": "DRAFT",
                    "planAmount": 10000,
                    "currencyCode": "USD"
                }
            }
        }
    ],
    "responseStatus": "SUCCESS",
    "responseCode": "ACCEPTED",
    "responseMessage": "Request Accepted"
}

Online Payments API