Webhooks

Overview

J.P. Morgan’s Global Payments API supports webhooks to notify your application of real-time status updates when an event occurs. Webhooks are more efficient for both the API provider and clients because applications don’t need to frequently poll for data to get status updates.

Before you begin

To enable webhooks, you will need to:

Contact your J.P. Morgan Representative to initiate an implementation request when you are ready to start using the J.P. Morgan Treasury Services API.
Complete the implementation process to receive the certificate necessary to set up a new callback. For more information, see Getting Started.

Tip

How webhooks work

When a payment initiation request is received, it is acknowledged with a successful 202 HTTP status that includes the endToEndId and firmRootId in the response body. A payment then triggers a callback to your registered callback with a PENDING status and continues to send you callbacks as the payment transitions into further status changes.

The payment initiation status webhook response is usually received within 30 seconds. The Global Payments API always provides the latest and most accurate information about the payment. If an HTTP error occurs, J.P. Morgan automatically retries until the error is no longer received.

Payment status webhooks

The webhooks are a callback to your client through the Global Payment API. For more information, see the Global Payments Open API Specification.

Confirm callback response

The following response shows a payment in the REJECTED state:

Example payment response: REJECTED

Json

{
  "callbacks": [
    {
      "endToEndId": "MY20230727_0219",
      "createDateTime": "2023-07-27T07:41:54.773Z",
      "paymentStatus": "REJECTED",
      "firmRootId": "53038faa-43f6-42fc-9545-648fd2dab411",
      "exceptions": [
        {
          "errorCode": "10004",
          "errorDescription": "Error occurred on /requestedExecutionDate",
          "ruleDefinition": "Date validation failure"
        }
      ]
    }
  ]
}

Resources

Status response types

The following table lists supported status response types by the Global Payments API.

Global Payments API status response types
Status	Description
PENDING	The payment is pending processing.
PENDING_POSTING	The payment is not posted in the beneficiary account.
COMPLETED	The payment was completed.
COMPLETED_CREDITED	The beneficiary’s account was credited.
REJECTED	The payment was rejected. For more information about the exception object for error details, see Callbacks in the Open API Specification.
RETURNED	The payment was returned to the debtor party.
BLOCKED	The payment was blocked due to a sanctions issue.
WAREHOUSED	The payment request was received and will be processed on the requested execution date.

Status transitions

The following table lists supported status transitions for all markets.

Global Payments API status transitions
Market	Status
All	PENDING -> COMPLETED PENDING -> REJECTED

The following table lists supported status transitions for regions that support additional flows.

Additional Global Payments API region status transitions
Market	Status
Hong Kong (FPS)	PENDING -> COMPLETED -> COMPLETED_CREDITED
United States (TCH)	PENDING -> PENDING_POSTING -> COMPLETED PENDING -> BLOCKED

Next steps

Learn how to test using mock data to trigger specific responses and error scenarios.