Skip to main content
optimization protection

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 types. 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": "RecurringProgramNotification", 
            "notificationDescription": "Notification of recurring payment", 
            "supportedSubTypes": [ 
                { 
                    "notificationSubType": "ProgramUpdated", 
                    "subTypeDescription": "Recurring program updated or created notification" 
                } 
            ] 
        } 
    ] 
}

Subscribe to event notifications

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. Include the callback URL you want to receive the notifications.  

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

Json
{
    "notifications": {
        "tokenLifecycleNotification": [
            "All"
        ],
        "recurringProgramNotification": [
            "PlanUpdated",
            "ConsumerCommunicationUpdated",
            "PaymentApplied",
            "PaymentNotApplied",
            "ProgramUpdated"
        ]
    },
    "securityPreferences": {
        "oAuthNotificationEnabled": true,
        "sslAuthNotificationEnabled": true,
        "headerFields": {
            "key1": "value1",
            "key2": "value2"
        },
        "oAuthDetails": {
            "oAuthClientSecret": "ab3sgdLdSX8szxD",
            "oAuthClientId": "sE4sasddaKJ4sfdfdEasQfsdAeeWaSa",
            "tokenURL": "https://api-uat.merchant.com/oauth/client_credential/accesstoken"
        }
    },
    "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"
    }
}

Retrieve subscription details

Retrieve details about your subscriptions 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"
}

Get a subscription by subscription ID

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

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

Json
{
    "subscriptionResponse": {
        "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",
        "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"
        }
    }
}

Update a subscription

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

Attention

Once a subscription is updated, the changes are effective immediately. Ensure 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"
    }
}

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" 
}