Subscriptions User Guide

Purpose

This guide provides an overview of subscriptions, including how to create and manage them, and highlights the differences between subscriptions and the legacy callback experience.

It is created for portal users who need to create, configure, or manage subscriptions for enabled API products.

Why use subscriptions?

Subscriptions give clients greater control by enabling self-service setup, subscription-level security preferences, custom retry handling and supported OAuth 2.0 connectivity directly through the Payments Developer Portal.

What are subscriptions?

Subscriptions are a self-serve capability that enables clients to receive event-driven notifications for API products. Clients can:

Subscribe to available event groups and event types based on their enabled API products.
Configure delivery preferences such as callback URL, connectivity method, retry preferences, and response preferences.
Manage, update, and delete their subscriptions based on their evolving needs.

Supported countries

Here is a list of countries supported by Subscriptions:

Supported countries
Availability	Countries/ regions
Currently supported	Americas: United States, Canada, Brazil, Mexico
	Europe: Europe, United Kingdom, Ireland, France, Germany, Spain, Italy, Sweden, Switzerland
	APAC: Australia, New Zealand, Japan, South Korea, India
Upcoming	Middle East: Saudi Arabia, UAE
	Americas: Chile, Brazil
	APAC: Thailand, Malaysia

What can users do with subscriptions?

Callback subscription capabilities
Capability	What it means
Subscribe to events	Choose relevant event groups and event types for an API product.
Configure delivery	Set the endpoint and delivery preferences used to send notifications.
Manage subscriptions	View or update subscription details as operational needs change.
Support secure delivery	Use supported security options such as mTLS or OAuth, based on your implementation requirements.
Handle delivery failures	Use configured retry preferences and delivery information to support troubleshooting.

Before you start

Before creating a subscription, confirm the following:

You have access to the correct client workspace and project in the Payments Developer Portal.
The relevant API product and event groups are available for the project.
You have prepared the callback endpoint URL that will receive notifications.
You know the supported security method for your setup, such as mTLS or OAuth.
You know which event groups and event types you want to receive.

Set up a subscription

Follow these steps to configure a subscription.

Open the relevant project in your client workspace, then select Callbacks from the left-hand navigation.
Under Subscriptions, select Create Subscription.
Enter the callback URL where notifications should be delivered, then select Next.
Choose the supported security method, such as mTLS or OAuth, based on your setup. You can upload a new certificate or use an existing one.
Set delivery preferences, including retry settings and response preferences.
Select Configure events to choose the event groups for the API.
Enable one or more events, then select Configure event group.
Select Create Subscription to finish the setup.
The subscription status will initially show as Configuring. Once it changes to Active, you receive an email confirmation.
Note: While the subscription is configuring, event groups are view-only.
After a subscription is created, backend setup steps are completed automatically, including certificate installation, system synchronization and a ping test to the callback URL to confirm it is reachable before the status changes to Active. If an incorrect callback URL is entered, the subscription becomes editable after approximately 4 hours so that the URL can be updated.

Configuring

Setup is in progress and event groups are view-only.

Active

The subscription is ready and notifications can be delivered.

Subscriptions statuses
Subscription Status	Meaning
Configuring	Setup is in progress and event groups are view-only.
Active	The subscription is ready and notifications can be delivered.

Schema example

The following example shows the standard eventData structure used for subscription notifications. Field values may vary by API product, event group, and event type.

Json

{ 

  "specversion": "<string: cloud event spec version>", 
  "id": "<string: event unique identifier>", 
  "time": "<string: event timestamp (ISO 8601 format)>", 
  "type": "<string: event type>", 
  "source": "<string: event source URI>", 
  "dataschema": "<string: Optional Data Schema>", 
  "data": { 
    ... 
   
}

Notification delivery — HTTP headers and content types

Headers you will always receive

Every notification delivery includes the following headers, regardless of your configuration:

Content-Type: Describes the format of the notification body. See the following table.
traceId: A unique identifier for the notification delivery. Use it for support queries and to correlate the delivery with your own logs.

Content-Type based on your security preference

Content type based on your security preference
Security preference	Content-Type
Encryption enabled	application/jose
Digital signature enabled (non-CloudEvents)	application/json
Digital signature enabled (CloudEvents)	application/cloudevents+json
No security preference (CloudEvents)	application/cloudevents+json
No security preference (non-CloudEvents)	application/json

Note

When encryption is enabled, the notification body is a fully encrypted JOSE token. You must decrypt it before processing the payload. The original payload format—JSON or CloudEvents—is contained within the token.

Digital signature headers

If you opt into digital signatures, every notification includes two additional headers:

jws-kid: identifies the signing key used. Use this value to findthe corresponding public key for verification.
jws-signature: contains the detached JWS signature of the notification body. Verify it against the body using the public key identified by jws-kid.

Attention

The signature is detached. The notification body is delivered unchanged, while the signature is sent separately in the headers. Your verifier should use the raw body bytes and validate them against the jws-signature value.

Authorization — OAuth clients only

If your subscription uses OAuth as the connection type, the publisher obtains a bearer token on your behalf and includes it in the outbound request. You do not need to take any additional action for inbound authentication. Your endpoint can use this header for its own access control, if required.

mTLS clients authenticate at the TLS layer and do not receive an Authorization header.

Manage a subscription

Manage subscription
Action	Use when
Reconfigure	You want to update the endpoint details or delivery preferences.
Manage events	You want to enable or remove event groups for a subscription.
Remove subscription	You no longer need notifications for that project or product. Note: Removing a subscription is permanent. If you need it again, you must configure a new subscription.

Reconfigure

You want to update the endpoint details or delivery preferences.

Manage events

You want to enable or remove event groups for a subscription.

Remove subscription

You no longer need notifications for that project or product.

Callback subscriptions compared with legacy callbacks

Legacy callbacks are managed by our onboarding partners and must be enabled on your behalf. Unlike callback subscriptions, they cannot be self-managed or configured directly. Once setup is complete, you will receive all configured events.

Note

New callback requests are expected to use subscriptions. Existing legacy callbacks will be migrated to callback subscriptions, based on product and implementation plans.

Callback subscriptions compared with legacy callbacks
Feature	Legacy callbacks	Subscriptions
Setup model	Configured by J.P. Morgan onboarding partners on the client’s behalf.	Created and managed by clients directly through the Payments Developer Portal.
Configuration ownership	Changes require coordination with onboarding or support teams.	Clients can update subscription settings as their operational needs change.
Event selection	Clients receive the events configured during onboarding.	Clients can choose available event groups and event types for enabled API products.
Security configuration	Security is configured as part of the onboarding setup.	Clients can configure security preferences independently for each subscription, including encryption and digital signature supported.
Retry handling	Retry behavior follows the configured legacy callback setup.	Clients can configure custom retry settings to manage failed notification of delivery attempts.
OAuth 2.0 connectivity	Connectivity options are defined during onboarding.	Clients can provide OAuth 2.0 identity provider details where supported. OAuth 2.0 is currently limited to selected client secret and password-based grant types, with additional grant types expected in future releases.

Key terms

Key terms
Term	Meaning
Event group	A group of related notifications for an API product or business outcome.
Event type	A specific notification within an event group.
Endpoint	The callback URL where the client system receives notifications.
Delivery preferences	Settings that control how notifications are sent, such as connectivity, retries and response requirements.
Proof of delivery	Delivery information used to help confirm and troubleshoot notification delivery.

Support

For help, raise a support request through the Payments Developer Portal, or contact support.

Raise a support request if:

The subscription status does not match your expected setup.
Notifications are not reaching your endpoint.
You need help with certificate, OAuth or mTLS configuration.

Disclaimer

This guide is for discussion and informational purposes only. Product availability, screens, labels and functionality may change. Always refer to the Payments Developer Portal and your J.P. Morgan team for the latest guidance. Not all products and services are available in all locations or to all clients. © 2026 JPMorgan Chase & Co. All rights reserved.