# JPMC-PDP Documentation from https://developer.payments.jpmorgan.com # 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 >
> 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. > ## 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](/api/commerce/optimization-protection/notifications/error-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", "subscriptionChannel": "WEBHOOK" }, { "notificationSubType": "PaymentDeclined", "subTypeDescription": "Event to notify that the payment has been declined", "subscriptionChannel": "WEBHOOK" }, { "notificationSubType": "PaymentErrored", "subTypeDescription": "Event to notify that the payment has been errored", "subscriptionChannel": "WEBHOOK" }, { "notificationSubType": "PaymentVoid", "subTypeDescription": "Event to notify that the payment has been voided", "subscriptionChannel": "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](/docs/commerce/optimization-protection/capabilities/notifications/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.preferredLanguage and recipientDetails.emailAddress. >
> 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 subscriptionChannel = 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 | | subscriptionChannel | 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 subscriptionChannel = 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" }, "subscriptionChannel": "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", "subscriptionChannel": "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" } ], "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", "subscriptionChannel": "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. > 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", "subscriptionChannel": "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" } ``` ## Related [Notification types](/docs/commerce/optimization-protection/capabilities/notifications/notification-types)