Skip to main content

Subscribe to notifications

The Notifications API generates notifications based on your notification subscriptions. In this guide, you will learn how to:

  • Retrieve notification types
  • Subscribe to notifications
  • Retrieve subscription details
  • Retrieve a subscription by subscription ID
  • Update a subscription
  • Delete a subscription

Before you begin

Learn how to retrieve and view the available notification event types, subtypes, and their supported subscription channels. To do this, perform the following steps:

  1. Send a GET request to the /notificationTypes endpoint.
  2. Confirm a successful response of HTTP 200 status. 
  3. Familiarize yourself with Notifications response codes.

The following is a sample response for the retrieval of all notification types:

HTTP method: GET
Endpoint: /notifications/notificationTypes

Json
{
    "notificationTypes": [
        {
            "notificationType": "PaymentUpdateNotification",
            "notificationDescription": "Payment Status information from Gateway",
            "supportedSubtypes": [
                {
                    "notificationSubType": "PaymentApproved",
                    "subTypeDescription": "Event to notify that the payment has been approved",
                    "subscriptionChannels": [
                        "WEBHOOK"
                    ]
                },
                {
                    "notificationSubType": "PaymentDeclined",
                    "subTypeDescription": "Event to notify that the payment has been declined",
                    "subscriptionChannels": [
                        "WEBHOOK"
                    ]
                },
                {
                    "notificationSubType": "PaymentErrored",
                    "subTypeDescription": "Event to notify that the payment has been errored",
                    "subscriptionChannels": [
                        "WEBHOOK"
                    ]
                },
                {
                    "notificationSubType": "PaymentVoid",
                    "subTypeDescription": "Event to notify that the payment has been voided",
                    "subscriptionChannels": [
                        "WEBHOOK"
                    ]
                }
            ]
        }
    ]
}

Subscribe to notification events

Complete the following steps to subscribe to an event notification:

  1. Identify the type and subtype of the notification. For more information about notification categories and subtypes, see Notification types.
  2. Create and send a POST request to the /subscriptions endpoint. 
  3. Choose the subscription channel: Webhook or Email
    • For webhooks, you must provide the callbackURL.
    • For emails, you must provide the recipientDetails.emailAddress.
Attention
A few things to keep in mind when you are subscribing to a notification:
  • If the callbackURL has query parameters, it must be encoded.
  • If you are subscribing with a callbackURL that requires usage of proxy or whitelisting, the subscription will be active only after a buffer of 60 mins.
Header details for subscribing to notifications
Header name Description
entity-id Unique identifier for the entity.
entity-type

The type of entity identifier. Valid values are:

  • MERCHANT
  • PLATFORM
  • CLIENT
  • ACCOUNT
request-id A unique identifier provided by the requestor for each request.
Required, optional, and conditional fields for subscribing to notifications
Field name Description Required (R), Optional (O), or Conditional (C)
recipientDetails Details of the individual recipient. O
recipientDetails.firstName The first part of an individual's full name considered a personal name or given name. Generally positioned before the last name or family name. O
recipientDetails.lastName That last part of an individual's name generally placed at the end of the given name. The last name is also known as the surname or family name. O
recipientDetails.emailAddress

The email address of the recipient that is used to send and receive messages electronically.

You must provide this field if the subscriptionChannels = EMAIL.

 C
recipientDetails.telephoneNumber The telephone number of the recipient. O
recipientDetails.telephoneCountryCode The telephone dialing prefix for a member country in the International Telecommunication Union (ITU) that is defined by the ITU-T E.164 standard. The code is a combination of one, two or three digits identifying a specific country, countries in an integrated numbering plan, or a specific geographic area. O
notifications Array of notification event types to subscribe. R
securityPreferences Object that holds information on the security preferences for sending notifications. O
subscriptionChannels

The list of mediums through which event notifications will be delivered to the merchant. Valid values are:

  • Webhook - notifications are sent in the form of a webhook to the callbackURL.
  • Email - notifications are sent in the form of an email to the recipientDetails.emailAddress.
 R
callbackURL

URL/Endpoint to receive Webhook notifications by merchant.

You must provide this field if the subscriptionChannels = WEBHOOK.

 C

The following example shows a request for subscribing to managed recurring program notifications:

HTTP method: POST
Endpoint: /subscriptions

Json
{
    "notifications": {
        "tokenLifecycleNotification": [
            "All"
        ],
        "recurringProgramNotification": [
            "PlanUpdated",
            "ConsumerCommunicationUpdated",
            "PaymentApplied",
            "PaymentNotApplied",
            "ProgramUpdated"
        ]
    },
    "securityPreferences": {
        "webhookAuthorizationType": "token",
        "tokenEndpointAuthorizationType": "client_secret_post",
        "mTLSEnabled": true,
        "authorizationDetails": {
            "clientSecret": "jhsh134hkjhjkh@3123",
            "clientId": "3e28334a-1b7d-480a-a35d-12345",
            "tokenEndpoint": "https://api-idp-server.com/merchant/v1/getToken"
        },
        "headerFields": {
            "Api-Key": "12345678"
        },
        "signingAlgorithm": "EC"
    },
    "subscriptionChannels": [
        "WEBHOOK"
    ],
    "callBackUrl": "https://merchant.notification.com"
}

Response:  

Json
{
    "notifications": {
        "tokenLifecycleNotification": [
            "All"
        ],
        "recurringProgramNotification": [
            "PlanUpdated",
            "ConsumerCommunicationUpdated",
            "PaymentApplied",
            "PaymentNotApplied",
            "ProgramUpdated"
        ]
    },
    "subscriptionId": "f07e8898-2819-44eb-989f-e04607766c10",
    "subscriptionCreatedTimestamp": "2024-01-09T10:05:42.522Z",
    "subscriptionUpdatedTimestamp": "2024-01-09T10:05:42.522Z",
    "callbackURL": "https://merchant.notification.com",
    "responseStatus": "SUCCESS",
    "responseCode": "ACCEPTED",
    "responseMessage": "Request Accepted",
    "publicKey": {
        "publicKeyIdentifier": "213db467b83c4db2a69da08705eff25a",
        "publicKeyText": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEvsoc/9/GmHzXSw7JBpGc7zJx5TYRJXmQxG2Dnx2BZ+ELQEliL6oCOUpAxx+TW61BmVdCabh+i43biOPicgXY/A==",
        "publicKeyExpirationDate": "2024-10-31T13:10:30.481Z"
    },
    "subscriptionChannels": [
        "WEBHOOK"
    ]
}

Retrieve all subscriptions by entity ID

Retrieve details about all your subscriptions for an entity-id by using a GET call to the /subscriptions endpoint. 

HTTP method: GET
Endpoint: /subscriptions

Json
{
    "subscriptionGetResponses": [
        {
            "notifications": {
                "tokenLifecycleNotification": [
                    "All"
                ]
            },
            "subscriptionId": "b65an74a-989e-43fb-867b-7d983c3e2c2c",
            "subscriptionCreatedTimestamp": "2021-05-05T09:52:25.686Z",
            "subscriptionUpdatedTimestamp": "2021-05-05T09:52:25.686Z",
            "callBackUrl": "https://merchant.notification.com"
        },
        {
            "notifications": {
                "recurringProgramNotification": [
                    "PlanUpdated"
                ]
            },
            "subscriptionId": "b65ab74a-989e-43fb-867b-7d983c3e2c2c",
            "subscriptionCreatedTimestamp": "2021-05-05T09:52:25.686Z",
            "subscriptionUpdatedTimestamp": "2021-05-05T09:52:25.686Z",
            "callBackUrl": "https://merchant.notification.com",
            "publicKey": {
                "publicKeyIdentifier": "213db467b83c4db2a69da08705eff25a",
                "publicKeyText": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEvsoc/9/GmHzXSw7JBpGc7zJx5TYRJXmQxG2Dnx2BZ+ELQEliL6oCOUpAxx+TW61BmVdCabh+i43biOPicgXY/A==",
                "publicKeyExpirationDate": "2024-10-31T13:10:30.481Z"
            }
        }
    ],
    "responseStatus": "Request Accepted",
    "responseCode": "ACCEPTED"
}

Retrieve a subscription by subscription ID

Retrieve a specific subscription by using the GET /subscriptions/{subscription-id} endpoint.

HTTP method: GET
Endpoint: /subscriptions /383597a6-e314-4322-a9b0-3ffc397eeedc

Json
{
    "notifications": {
        "paymentUpdateNotification": [
            "All"
        ]
    },
    "subscriptionId": "383597a6-e314-4322-a9b0-3ffc397eeedc",
    "subscriptionCreateTimestamp": "2024-10-03T11:15:42.014Z",
    "subscriptionUpdatedTimestamp": "2024-10-03T11:43:28.922Z",
    "callbackURL": "https://merchant.notification.com",
    "subscriptionChannels": [
        "WEBHOOK"
    ],
    "responseStatus": "SUCCESS",
    "responseCode": "ACCEPTED",
    "responseMessage": "Request Accepted"
}

Update a subscription

Update the callback URL and the list of enabled events of a subscription by using a PUT call to the /subscriptions/{subscription-id} endpoint.

Attention

A few things to keep in mind when updating a webhook subscription:

  • If you are updating the callbackURL of a subscription, the update takes effect after one hour. 
  • If you are not updating the callbackURL of a subscription, the changes are effective immediately. 
    • Ensure that you are ready to start handling the updated notifications immediately after you make this request. 
  • This request will only impact the subscription you update.

HTTP method: PUT
Endpoint: /subscriptions /{subscription-id}

Json
{ 
    "notifications": { 
        "tokenLifecycleNotification": [ 
            "All" 
        ] 
    }, 
    "callBackUrl": "https://merchant.notification.com" 
}

Response:

Json
{
    "notifications": {
        "tokenLifecycleNotification": [
            "All"
        ]
    },
    "subscriptionId": "383597a6-e314-4322-a9b0-3ffc397eeedc",
    "subscriptionCreatedTimestamp": "2021-04-21T10:39:09.953Z",
    "subscriptionUpdatedTimestamp": "2021-04-21T10:39:09.953Z",
    "callbackURL": "https://merchant.notification.com",
    "secretKey": "f7YS26u#PV#NuZLXXiNYsCregH7WgXUhX",
    "responseStatus": "SUCCESS",
    "responseCode": "ACCEPTED",
    "responseMessage": "Request Accepted",
    "publicKey": {
        "publicKeyIdentifier": "213db467b83c4db2a69da08705eff25a",
        "publicKeyText": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEvsoc/9/GmHzXSw7JBpGc7zJx5TYRJXmQxG2Dnx2BZ+ELQEliL6oCOUpAxx+TW61BmVdCabh+i43biOPicgXY/A==",
        "publicKeyExpirationDate": "2024-10-31T13:10:30.481Z"
    },
    "subscriptionChannels": [
        "WEBHOOK"
    ]
}

Delete a subscription

Delete the subscription by using a DELETE call to the /subscriptions/{subscription-id} endpoint using the subscription ID you want to delete.  

HTTP method: DELETE
Endpoint: /subscriptions /{subscription-id}

Json
{ 
    "responseStatus": "SUCCESS", 
    "responseCode": "ACCEPTED", 
    "responseMessage": "Request Accepted" 
}