API References

Authentication

J.P. Morgan uses Mutual Transport Layer Security (mTLS) to authenticate API requests. This highly secure authentication standard utilizes mutual certificate authentication and requires that each entity involved in the communication is verified before any sensitive data is transmitted. For additional information on creating certificates and configuring credentials for API access, please see the “Getting Started” section of the API reference documentation for the API you are interested in using.

HTTP Response Codes

J.P. Morgan follows standard HTTP conventions to indicate the success or failure of an API request. You should refer to the API reference documentation for an exhaustive list of error codes for each API.

In general: 

• Codes in the 2xx range indicate success.
• Codes in the 4xx range indicate a failure to execute the request with the information provided. This might represent a mal-formed request or a synchronous action that fails for business reasons (e.g. insufficient funds, invalid account, etc.).
• Codes in the 5xx range represent interruptions in service.

The following is a non-exhaustive list of statuses you might receive:

The majority of error responses contain additional information to aid in problem diagnosis. Review the associated API documentation for use-case specific guidance.

Versioning

J.P. Morgan Payments Platform APIs will evolve over time for a number of reasons including, but not limited to, strategic shifts in business operations and/or the evolution of our software platforms.

To ensure a durable and predictable client experience we will:

• Adhere to a clear API versioning strategy.
• Provide clear and succinct documentation and client communications.
• Be fully transparent when functionality is due to be deprecated and/or decommissioned. 

Versioning Strategy

J.P. Morgan's Payments Platform versioning strategy allows for our APIs to evolve in without breaking client integrations (subject to guidance below) as such changes are rolled out. We follow the Semantic Versioning  approach to identify breaking and non-breaking changes.

Integration Expectations

• Our versioning model allows for API responses to evolve over time. This means that integrations must tolerate the presence of previously unexpected JSON properties in response payloads.
• Clients should also monitor for the existence of the following HTTP headers:
  • Deprecation – Indicates that the capability is, or will be, deprecated.
  • Sunset – Indicates when the capability is due to be removed.

How It Works

A common numbering scheme is illustrated in the following image:

• Major version: This number increments if a non-backward compatible change is made. For example, a change to version 1.2.4 will result in a new version 2.0.0.
• Minor version: This number increments when a backward-compatible change is made, e.g. adding a new operations to an existing API. For example, a change to version 1.2.4 will result in a new version 1.3.0. 
• Patch version: This number is incremented for compatible bug fixes, e.g., changing and clarifying the documentation in an API contract. For example, a compatible bug fix to version 1.2.4 will result in a new version 1.2.5.

Types of Changes

Non-Breaking Changes

Non-Breaking changes are those that typically don't break your existing application using the API. These include minor bug fixes and non-breaking feature updates.

The following are a few examples of changes we consider as non-breaking:

• Addition of new resources and endpoints
• Addition of new optional request fields or parameters
• Changes to the order of fields returned within a response
• Bug fixes on existing APIs
• Deprecating an existing API

This is how non-breaking changes are handled:

• No new (URL-level) version will be created.
• Version number will be updated as follows:
  • First set of number to be consistent with the (URL) version of the API.
  • Second set of number to indicate minor changes.
  • Third set of number to indicate secondary minor changes (a patch, fixing issue). 

Breaking Changes

The introduction of a new major API version will cause future disruption to your existing applications. We recommend migrating to the new version of the API as soon as possible.

The following are a few examples of changes we consider as breaking:

• Removal of a mandatory request or response field
• Addition of a required/optional request field without default values
• Changes to the intended functionality of an endpoint
• Introduction of a new field validation
• Changing data type of an existing field
• Removing or renaming the URL of an endpoint
• Adding a required header to an existing endpoint
• Changing existing error codes/messages
• Introducing new features such as payload signing, additional encryption etc. 
• Modifying the existing payload of webhooks or async callbacks
• Retiring an API

This is how breaking changes are handled:

• A new version of the API will be created and swagger documentation for the new version will be published on Developer Portal. 
• Previous version of the API is marked on the Developer Portal as "deprecated".
• Version number (within Information section) will be updated as:
  • First set of number to indicate major changes and be consistent with the (URL) version of the API.
  • Second set of number to indicate minor changes

Communication

As J.P. Morgan Payments Platform APIs evolve, J.P. Morgan will make reasonable efforts to notify you of breaking changes in advance with sufficient time to adapt to these changes.

• Changelog on the Developer Portal will be updated with technical specifications.
• Email communication will be sent to client contacts.

Deprecation Strategy

Release States

Active

The API is ready for Production use. APIs are fully supported with new features and bug fixes in subsequent releases. The complete API documentation will be available on the developer portal.

Deprecated

Deprecation is the first step toward retirement of an API version, this can be as a result of a new major version becoming available, or a future curtailment of service.

• Functionality is typically maintained for a period of 18 months prior to permanent retirement. 
• Functionality is operational and fully supported, new integrations are strongly discouraged, and may be prohibited in some situations.
• No new features will be added, existing applications should update to the active version of the API to prevent future service interruption.

Retired

Retired APIs are no longer available, supported, or documented.