Notifications API
Notification API enables merchants to subscribe to and receive notifications in real-time.
OpenAPI Specification
# Harvested verbatim from the J.P. Morgan Payments Developer Portal.
# method: searched
# source: https://developer.payments.jpmorgan.com/api/llm-content?path=en%2Fapi%2Fcommerce%2Foptimization-protection%2Fnotifications%2Fnotifications-oas.md
# generated: '2026-07-28'
openapi: 3.0.1
info:
title: Notifications API
description: Notification API enables merchants to subscribe to and receive notifications in real-time.
version: 1.13.1
contact:
name: Notifications API Support
url: https://developer.payments.jpmorgan.com/contact/support
servers:
- url: https://mns-aws.jpmchase.com/v1
description: PRODUCTION - OAUTH
- url: https://mns-aws-cat.jpmchase.com/v1
description: CLIENT TESTING - OAUTH
- url: https://api-mock.payments.jpmorgan.com/v1
description: MOCK
security:
- BearerAuth: []
tags:
- name: Subscriptions
description: Manage notification subscriptions
- name: Notifications
description: Obtain notifications
- name: Health Check
description: Validate the health of the service
paths:
/healthcheck/notification-subscriptions:
get:
summary: Health check for the Notification Subscription service
security: []
operationId: v1GetSubscriptionsHealth
tags:
- Health Check
description: Health check endpoint to validate that the Notification Subscription service is running
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/healthCheckResource'
examples:
Success:
value:
status: PASS
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
/notifications/{notification-id}:
get:
summary: Get a notification by notification Id
operationId: v1GetNotificationByNotificationId
tags:
- Notifications
description: Retrieves a specific notification using the notification Id
parameters:
- name: merchant-id
in: header
deprecated: true
schema:
type: string
pattern: ^[0-9]{8,12}$
description: Identifier for the merchant account.
examples:
Success:
value: '9876543210'
Authentication failure:
value: '9876543211'
Authorization failure:
value: '9876543212'
Notification not found:
value: '9876543213'
- name: request-id
in: header
required: true
schema:
type: string
format: uuid
description: A unique identifier provided by the requestor for each request.
examples:
Success:
value: 7611d1bf-325c-4795-a828-ac21f9bea5dc
Authentication failure:
value: 7611d1bf-325c-4795-a828-ac21f9bea7ab
Authorization failure:
value: 7611d1bf-325c-4795-a828-ac21f9bea8dc
Notification not found:
value: 7611d1bf-325c-4795-a828-ac21f9bea6ab
- name: notification-id
in: path
required: true
schema:
type: string
format: uuid
description: A unique identifier provided by the requestor for each request.
examples:
Success:
value: 44444444-4017-11e9-b649-8de064221544
Authentication failure:
value: 44444444-4017-11e9-b649-8de064221234
Authorization failure:
value: 44444444-4017-11e9-b649-8de064224567
Notification not found:
value: 44444444-4017-11e9-b649-8de064227890
- name: entity-id
in: header
required: true
schema:
type: string
pattern: ^[0-9]{8,12}$
description: Identifier for the entity.
examples:
Success:
value: '9876543210'
Authentication failure:
value: '9876543211'
Authorization failure:
value: '9876543212'
Notification not found:
value: '9876543213'
- name: entity-type
in: header
required: true
schema:
type: string
enum:
- MERCHANT
- PLATFORM
- CLIENT
- ACCOUNT
- EMBEDDED_PLATFORM
- CONSUMER
description: Type of entity identifier.
examples:
Success:
value: MERCHANT
Authentication failure:
value: PLATFORM
Authorization failure:
value: CLIENT
Notification not found:
value: ACCOUNT
- name: subscription-channel
in: header
schema:
type: string
enum:
- WEBHOOK
- EMAIL
- IN-APP-COMMERCE-CENTER
description: List of medium through which event notifications will be delivered to recipient.
examples:
Success:
value: WEBHOOK
Authentication failure:
value: EMAIL
Authorization failure:
value: WEBHOOK
Notification not found:
value: EMAIL
- name: parent-entity-id
in: header
schema:
type: string
pattern: ^[0-9]{8,12}$
description: Identifies the Parent Entity in the merchant hierarchy applicable to this request
(e.g. platform ID in ISV use cases).
examples:
Success:
value: 0123456797
Authentication failure:
value: 0123456798
Authorization failure:
value: 0123456799
- name: parent-entity-type
in: header
schema:
type: string
enum:
- PLATFORM
- EMBEDDED_PLATFORM
description: Code for the Parent Entity Type in the merchant hierarchy applicable to this request
(e.g. platform in ISV use cases).
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/notificationResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/adfsError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
/subscriptions:
get:
summary: Get all subscriptions by entity Id
operationId: v1ListSubscriptions
tags:
- Subscriptions
description: Retrieves all subscriptions using the entity Id
parameters:
- name: merchant-id
in: header
deprecated: true
schema:
type: string
pattern: ^[0-9]{8,12}$
description: Identifier for the merchant account.
examples:
Success:
value: '9876543210'
Authentication failure:
value: '9876543211'
Authorization failure:
value: '9876543212'
- name: entity-id
in: header
required: true
schema:
type: string
pattern: ^[0-9]{8,12}$
description: Identifier for the entity.
examples:
Success:
value: '9876543210'
Authentication failure:
value: '9876543211'
Authorization failure:
value: '9876543212'
- name: entity-type
in: header
required: true
schema:
type: string
enum:
- MERCHANT
- PLATFORM
- CLIENT
- ACCOUNT
- EMBEDDED_PLATFORM
- CONSUMER
description: Type of entity identifier.
- name: request-id
in: header
required: true
schema:
type: string
format: uuid
description: A unique identifier provided by the requestor for each request.
examples:
Success:
value: 7611d1bf-325c-4795-a828-ac21f9bea5dc
Authentication failure:
value: 7611d1bf-325c-4795-a828-ac21f9bea7ab
Authorization failure:
value: 7611d1bf-325c-4795-a828-ac21f9bea8dc
- name: notification-type
in: header
schema:
type: string
description: The first level categories of events the firm uses to communicate with the merchant.
- name: parent-entity-id
in: header
schema:
type: string
pattern: ^[0-9]{8,12}$
description: Identifies the Parent Entity in the merchant hierarchy applicable to this request
(e.g. platform ID in ISV use cases).
examples:
Success:
value: 0123456797
Authentication failure:
value: 0123456798
Authorization failure:
value: 0123456799
- name: parent-entity-type
in: header
schema:
type: string
enum:
- PLATFORM
- EMBEDDED_PLATFORM
description: Code for the Parent Entity Type in the merchant hierarchy applicable to this request
(e.g. platform in ISV use cases).
- name: email-address
in: header
schema:
type: string
description: A mail system that allows a party to send and receive messages electronically. An
email address is composed of a local part and a domain part. The local part is unique to the
individual while the domain or host name must meet specific standards required by the host that
administers the email service.
- name: subscription-category
in: header
schema:
type: string
description: Delineates a set of rules for the management of a subscription.
- name: subscription-channel
in: header
schema:
type: string
description: Codifies the method in which the Firm communicates with the Party.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/subscriptionResponseList'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/adfsError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
post:
summary: Subscribe to a notification
operationId: v1CreateSubscription
tags:
- Subscriptions
description: Create subscriptions to notification event types
parameters:
- name: merchant-id
in: header
deprecated: true
schema:
type: string
pattern: ^[0-9]{8,12}$
description: Identifier for the merchant account.
examples:
Success:
value: '9876543210'
Authentication failure:
value: '9876543211'
Authorization failure:
value: '9876543212'
- name: entity-id
in: header
required: true
schema:
type: string
pattern: ^[0-9]{8,12}$
description: Identifier for the entity.
examples:
Success:
value: '9876543210'
Authentication failure:
value: '9876543211'
Authorization failure:
value: '9876543212'
- name: request-id
in: header
required: true
schema:
type: string
format: uuid
description: A unique identifier provided by the requestor for each request.
examples:
Success:
value: 7611d1bf-325c-4795-a828-ac21f9bea5dc
Authentication failure:
value: 7611d1bf-325c-4795-a828-ac21f9bea7ab
Authorization failure:
value: 7611d1bf-325c-4795-a828-ac21f9bea8dc
- name: entity-type
in: header
required: true
schema:
type: string
enum:
- MERCHANT
- PLATFORM
- CLIENT
- ACCOUNT
- EMBEDDED_PLATFORM
- CONSUMER
description: Type of entity identifier.
- name: parent-entity-id
in: header
schema:
type: string
pattern: ^[0-9]{8,12}$
description: Identifies the Parent Entity in the merchant hierarchy applicable to this request
(e.g. platform ID in ISV use cases).
examples:
Success:
value: 0123456797
Authentication failure:
value: 0123456798
Authorization failure:
value: 0123456799
- name: parent-entity-type
in: header
schema:
type: string
enum:
- PLATFORM
- EMBEDDED_PLATFORM
description: Code for the Parent Entity Type in the merchant hierarchy applicable to this request
(e.g. platform in ISV use cases).
requestBody:
description: Create a new subscription
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/subscription'
examples:
Success:
value:
recipientDetails:
firstName: John
lastName: Doe
emailAddress: john.doe@myemail.com
telephoneNumber: 800-980-9890
telephoneCountryCode: '+1'
preferredLanguage: en-US
notifications:
paymentUpdateNotification:
- All
callbackURL: https://merchant.notification.com
subscriptionChannel: WEBHOOK
subscriptionChannels:
- WEBHOOK
Success Payout:
value:
recipientDetails:
firstName: John
lastName: Doe
emailAddress: john.doe@myemail.com
telephoneNumber: 800-980-9890
telephoneCountryCode: '+1'
notifications:
payoutNotification:
- All
subscriptionChannel: EMAIL
subscriptionChannels:
- EMAIL
Success Client Secret Post:
value:
notifications:
paymentUpdateNotification:
- All
securityPreferences:
webhookAuthorizationType: token
tokenEndpointAuthorizationType: client_secret_post
mTLSEnabled: false
authorizationDetails:
clientCredentials:
clientId: 3e28334a-1b7d-490a-a35d-12345e80e87
clientSecret: n1onto1n1on
contentType: application/json
clientCredentialRequestBody:
grant_type: client_credentials
scope: CASHIER.GET_ACCESS
tokenEndpoint: AUTH_ENDPOINT
callbackURL: https://merchant.notification.com
subscriptionChannel: WEBHOOK
subscriptionChannels:
- WEBHOOK
Success Private Key Jwt:
value:
notifications:
paymentUpdateNotification:
- All
securityPreferences:
webhookAuthorizationType: token
tokenEndpointAuthorizationType: private_key_jwt
mTLSEnabled: false
authorizationDetails:
tokenEndpoint: AUTH_ENDPOINT
jwtDetails:
jwtHeaderFields:
typ: JWT
alg: RS256
kid: kid
jwtRequestBody:
sub: dsd5yhuyuiyok5vQMZdZT3o
iss: //mns-aws.jpmchase.com
aud: jpmchase.com
jwtRequestParameters:
grant_type: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion: CLIENT_ASSERTION_JWT
signingAlgorithm: RSA
callbackURL: https://merchant.notification.com
subscriptionChannel: WEBHOOK
subscriptionChannels:
- WEBHOOK
Authentication failure:
value:
notifications:
disputeNotification:
- All
subscriptionChannel: EMAIL
subscriptionChannels:
- EMAIL
Authorization failure:
value:
notifications:
disputeNotification:
- All
callbackURL: https://merchant.notification.com
subscriptionChannel: WEBHOOK
subscriptionChannels:
- WEBHOOK
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/subscriptionsResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/adfsError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
/subscriptions/{subscription-id}:
get:
summary: Get a subscription by subscription Id
operationId: v1GetSubscriptionBySubscriptionId
tags:
- Subscriptions
description: Retrieves a specific subscription using the subscription Id
parameters:
- name: request-id
in: header
required: true
schema:
type: string
format: uuid
description: A unique identifier provided by the requestor for each request.
examples:
Success:
value: 7611d1bf-325c-4795-a828-ac21f9bea5dc
Authentication failure:
value: 7611d1bf-325c-4795-a828-ac21f9bea7ab
Authorization failure:
value: 7611d1bf-325c-4795-a828-ac21f9bea8dc
Subscription not found:
value: 7611d1bf-325c-4795-a828-ac21f9bea6ab
Subscription Identifier Invalid:
value: 7611d1bf-325c-4795-a828-ac21f9bea3ab
- name: merchant-id
in: header
deprecated: true
schema:
type: string
pattern: ^[0-9]{8,12}$
description: Identifier for the merchant account.
examples:
Success:
value: '9876543210'
Authentication failure:
value: '9876543211'
Authorization failure:
value: '9876543212'
Subscription not found:
value: '9876543213'
Subscription Identifier Invalid:
value: '9876543214'
- name: subscription-id
in: path
required: true
schema:
type: string
format: uuid
description: A unique identifier provided by the requestor for each request.
examples:
Success:
value: 7611d1bf-326d-4795-a828-ac21f9bea5dc
Authentication failure:
value: 7611d1bf-326d-4795-a828-ac21f9bea6dc
Authorization failure:
value: 7611d1bf-326d-4795-a828-ac21f9bea7dc
Subscription not found:
value: f56f4c9c-f5d5-44db-8fc7-bd8155406d76
Subscription Identifier Invalid:
value: f561d1bf-326d-4795-a828-ac21f9bea555
- name: entity-id
in: header
required: true
schema:
type: string
pattern: ^[0-9]{8,12}$
description: Identifier for the entity.
examples:
Success:
value: '9876543210'
Authentication failure:
value: '9876543211'
Authorization failure:
value: '9876543212'
- name: entity-type
in: header
required: true
schema:
type: string
enum:
- MERCHANT
- PLATFORM
- CLIENT
- ACCOUNT
- EMBEDDED_PLATFORM
- CONSUMER
description: Type of entity identifier.
- name: parent-entity-id
in: header
schema:
type: string
pattern: ^[0-9]{8,12}$
description: Identifies the Parent Entity in the merchant hierarchy applicable to this request
(e.g. platform ID in ISV use cases).
examples:
Success:
value: 0123456797
Authentication failure:
value: 0123456798
Authorization failure:
value: 0123456799
- name: parent-entity-type
in: header
schema:
type: string
enum:
- PLATFORM
- EMBEDDED_PLATFORM
description: Code for the Parent Entity Type in the merchant hierarchy applicable to this request
(e.g. platform in ISV use cases).
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/subscriptionResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/adfsError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
put:
summary: Update a specific subscription
operationId: v1UpdateSubscriptionBySubscriptionId
tags:
- Subscriptions
description: Update a specific subscription. Keep in mind that excluded fields will be interpreted
as `null`. To avoid inadvertently removing data, be sure to send the existing fields as-is in
addition to the fields being updated.
parameters:
- name: request-id
in: header
required: true
schema:
type: string
format: uuid
description: A unique identifier provided by the requestor for each request.
examples:
Success:
value: 7611d1bf-325c-4795-a828-ac21f9bea5dc
Authentication failure:
value: 7611d1bf-325c-4795-a828-ac21f9bea7ab
Authorization failure:
value: 7611d1bf-325c-4795-a828-ac21f9bea8dc
Subscription not found:
value: 7611d1bf-325c-4795-a828-ac21f9bea6ab
Subscription Identifier Invalid:
value: 7611d1bf-325c-4795-a828-ac21f9bea3ab
- name: merchant-id
in: header
deprecated: true
schema:
type: string
pattern: ^[0-9]{8,12}$
description: Identifier for the merchant account.
examples:
Success:
value: '9876543210'
Authentication failure:
value: '9876543211'
Authorization failure:
value: '9876543212'
Subscription not found:
value: '9876543213'
Subscription Identifier Invalid:
value: '9876543214'
- name: subscription-id
in: path
required: true
schema:
type: string
format: uuid
description: A unique identifier provided by the requestor for each request.
examples:
Success:
value: 7611d1bf-326d-4795-a828-ac21f9bea5dc
Authentication failure:
value: 7611d1bf-326d-4795-a828-ac21f9bea7dc
Authorization failure:
value: 7611d1bf-326d-4795-a828-ac21f9bea9dc
Subscription not found:
value: f56f4c9c-f5d5-44db-8fc7-bd8155406d76
Subscription Identifier Invalid:
value: f561d1bf-326d-4795-a828-ac21f9bea555
- name: entity-id
in: header
required: true
schema:
type: string
pattern: ^[0-9]{8,12}$
description: Identifier for the entity.
examples:
Success:
value: '9876543210'
Authentication failure:
value: '9876543211'
Authorization failure:
value: '9876543212'
- name: entity-type
in: header
required: true
schema:
type: string
enum:
- MERCHANT
- PLATFORM
- CLIENT
- ACCOUNT
- EMBEDDED_PLATFORM
- CONSUMER
description: Type of entity identifier.
- name: parent-entity-id
in: header
schema:
type: string
pattern: ^[0-9]{8,12}$
description: Identifies the Parent Entity in the merchant hierarchy applicable to this request
(e.g. platform ID in ISV use cases).
examples:
Success:
value: 0123456797
Authentication failure:
value: 0123456798
Authorization failure:
value: 0123456799
- name: parent-entity-type
in: header
schema:
type: string
enum:
- PLATFORM
- EMBEDDED_PLATFORM
description: Code for the Parent Entity Type in the merchant hierarchy applicable to this request
(e.g. platform in ISV use cases).
requestBody:
description: Update an existing notification subscription
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/subscription'
examples:
Success:
value:
recipientDetails:
firstName: John
lastName: Doe
emailAddress: john.doe@myemail.com
telephoneNumber: 800-980-9890
telephoneCountryCode: '+1'
preferredLanguage: en-US
notifications:
paymentUpdateNotification:
- All
callbackURL: https://merchant.notification.com
subscriptionChannel: WEBHOOK
subscriptionChannels:
- WEBHOOK
Authentication failure:
value:
notifications:
disputeNotification:
- All
callbackURL: https://merchant.notification.com
subscriptionChannel: EMAIL
subscriptionChannels:
- EMAIL
Authorization failure:
value:
notifications:
disputeNotification:
- All
callbackURL: https://merchant.notification.com
subscriptionChannel: WEBHOOK
subscriptionChannels:
- WEBHOOK
Subscription not found:
value:
notifications:
disputeNotification:
- All
callbackURL: https://merchant.notification.com
subscriptionChannel: EMAIL
subscriptionChannels:
- EMAIL
Subscription Identifier Invalid:
value:
notifications:
disputeNotification:
- All
callbackURL: https://merchant.notification.com
subscriptionChannel: WEBHOOK
subscriptionChannels:
- WEBHOOK
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/subscriptionsResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/adfsError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/com
# --- truncated at 32 KB (455 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/jp-morgan-chase/refs/heads/main/openapi/jp-morgan-chase-notifications-api-openapi.yml