Skip to main content
Jp Morgan Wallet

Notifications

Overview

J.P. Morgan Wallet™ can send you notifications when events related to financial transactions occur within your Wallet structure. These involve both physical movements of funds (such as funding a Wallet Demand Deposit Account, or DDA) and virtual movements of funds (such as moving funds between virtual accounts).

Wallet sends notifications for the following transaction types:

Notifications contain JSON data about the transaction, such as the current balances of virtual accounts and debtor/creditor information. Rather than regularly sending API requests to get information about your virtual accounts or transactions, you can get this information from notifications that Wallet automatically sends to you.

There are two types of notifications, which are explained in the following sections.

Terminal notifications

A terminal notification is sent when a transaction reaches a terminal state. The following are examples of terminal states.

Terminal states
State Description Transaction status code
CANCELLED The transaction was successfully cancelled after a cancellation request. CANC
COMPLETED The transaction was fully processed and settlement is complete. ACSC
COMPLETED_WITH_EXCEPTIONS The transaction completed but threw one or more exceptions. ACWP
REJECTED The transaction was rejected due to errors or failed validations. RJCT

Interim notifications

An interim notification is sent when a PayOut transaction reaches an interim state. The following are examples of interim states.

Interim states
State Description Transaction status code
ACCEPTED The transaction passed technical validation and was accepted for processing. ACSP
INITIATED The transaction was initiated. RCVD
PARTIALLY_COMPLETED Only part of the transaction was completed. PART
PENDING The transaction is pending further checks. PDNG

Subscribe to notifications

You can subscribe to notifications for any terminal or interim states when we set up your Wallet program. To subscribe to additional notifications after setting up your Wallet program, contact your J.P. Morgan representative.

Every client should subscribe to terminal notifications. In addition, you might also want to subscribe to interim notifications if you expect your transactions to take a long time. That way, you can continuously get progress updates on your transactions without needing to wait for them to complete.

Example

The following is an example of a terminal notification for the movement of funds from one DDA to another.

Example notification
Json
{
    "originalInstructionIdentification": "PIDeac54845ed0ede5f54f006bbfb321df8",
    "originalEndToEndIdentification": "WAL119ZY5CLT9P5",
    "transactionStatus": "ACSC",
    "statusReasonInformation": [
        {
            "additionalInformation": [
                "/eventType/PaymentComplete"
            ]
        }
    ],
    "acceptanceDateTime": "2023-09-13T21:56:46.563+0000",
    "accountServicerReference": "WAL119ZY5CLT9P5",
    "originalTransactionReference": {
        "amount": {
            "instructedAmount": {
                "amount": 499,
                "currency": "USD"
            }
        },
        "requestedExecutionDate": "2023-09-13",
        "paymentMethod": "BOOK",
        "debtorAccount": {
            "identification": {
                "other": {
                    "identification": "XXXXXXXXXX"
                }
            },
            "currency": "USD"
        },
        "debtorAgent": {
            "financialInstitutionIdentification": {
                "bic": "XXXXXXXXXXX"
            }
        },
        "creditorAgent": {
            "financialInstitutionIdentification": {
                "bic": "XXXXXXXXXXX",
                "name": "XXXXXXXX",
                "postalAddress": {
                    "country": "US"
                }
            }
        },
        "creditorAccount": {
            "identification": {
                "other": {
                    "identification": "XXXXXXXXXX"
                }
            },
            "currency": "USD"
        }
    }
}

Important fields

Notifications contain several key fields that provide detailed information about transactions. The following are some of the most important fields commonly included in these notifications.

Important notification fields
Field Description
acceptanceDateTime Date and time when the transaction was accepted or processed.
accountServicerReference Reference number that we assign to the transaction. Provide this to us when asking for support with a particular transaction.
originalEndToEndIdentification Unique end-to-end transaction identifier that enables you to tie the notification back to the original transaction.
originalInstructionIdentification Unique identifier for the original request that the client sent.
originalTransactionReference.amount Transaction amount and currency.
originalTransactionReference.creditorAccount Information about the account to which funds are credited (might be masked for security).
originalTransactionReference.creditorAgent Information about the financial institution of the creditor (might be masked for security).
originalTransactionReference.debtorAccount Information about the account from which funds are debited (might be masked for security).
originalTransactionReference.debtorAgent Information about the financial institution of the debtor (might be masked for security).
originalTransactionReference.paymentMethod Method used for the payment. For more information about payment methods, see Payments - Payment methods.
originalTransactionReference.requestedExecutionDate Date on which the client requested that the transaction be executed. For more information about requested execution dates, see Payments - Requested execution date.
statusReasonInformation.additionalInformation Array providing additional information about the transaction status, such as the event type or error details. For more information, see statusReasonInformation.additionalInformation field.
transactionStatus Current status of the transaction. For more information about transaction status codes, see Payments - Transaction status codes.

statusReasonInformation.additionalInformation field

The statusReasonInformation.additionalInformation field in the notification is an array of strings providing additional information in specific formats. The primary information that the field provides is the type of the event that caused the notification and information about the balances of the associated Virtual Transaction Accounts (VTAs).

The following is an example of the statusReasonInformation.additionalInformation field in the notification.

Example notification: statusReasonInformation.additionalInformation
Json
{
    "statusReasonInformation": [
        {
            "additionalInformation": [
                "/eventType/PaymentComplete",
                "/POSTED-BALANCE:ultimateDebtor:ACCOUNT-TYPE/TRANSACTION",
                "/POSTED-BALANCE:ultimateDebtor:VERSION/153",
                "/POSTED-BALANCE:ultimateDebtor:ITBD/5705832421.58",
                "/POSTED-BALANCE:ultimateDebtor:ITAV/-99917522.270",
                "/POSTED-BALANCE:ultimateDebtor:XPCD/5705832421.58",
                "/POSTED-BALANCE:ultimateDebtor:EFFECTIVE-DATE/2023-09-19",
                "/POSTED-BALANCE:ultimateDebtor:TIMESTAMP/2023-09-19T12:02:29.185+00:00"
            ]
        }
    ]
}

Event types

Every notification is caused by a specific event—that is, when a transaction reaches a state that you are subscribed to. For example, the PaymentComplete event occurs when a transaction reaches the COMPLETED terminal state. If you are subscribed to notifications for this state, then you will receive notifications for this event.

The event type is presented in the following format: /eventType/{EventType}

The following table lists the different event types in notifications.

Event types
Event type Description Example
PaymentComplete The transaction was completed. /eventType/PaymentComplete
NoticeOfChange A Notice of Change (NOC) was received. For more information, see Notice of Change. /eventType/NoticeOfChange

Virtual account balance information

If a transaction changes the balance of a VTA, the notification provides real-time balance information for that VTA in the statusReasonInformation.additionalInformation field.

This balance information is presented in the following format: /POSTED-BALANCE:{ultimateDebtor|ultimateCreditor}:{KEY}/{VALUE}

  • POSTED-BALANCE: Indicates that this string contains balance information for a virtual account.
  • {ultimateDebtor|ultimateCreditor}: Indicates whether this information is for a debited or credited virtual account.
  • {KEY}: Indicates the type of value.
  • {VALUE}: The actual value.

You can use this information to keep track of your virtual account balances rather than regularly sending API requests to check balances. If you need to do a one-off check of a VTA balance, see Get details about a virtual account - Get the balance of a Virtual Transaction Account.

The notification provides information about different types of balances, such as ITBD. For more information about the different balance types, see Get details about a virtual account - Balance types.

The following table lists the different balance information presented in the statusReasonInformation.additionalInformation field of the notification.

Virtual account balance information in notification
Key Description Example
ACCOUNT-TYPE Type of the account. /POSTED-BALANCE:ultimateDebtor:ACCOUNT-TYPE/TRANSACTION (VTA)
EFFECTIVE-DATE Effective date of the balance. /POSTED-BALANCE:ultimateDebtor:EFFECTIVE-DATE/2023-09-19
ITAV Value date balance (actual balance available for use, after pending debits). /POSTED-BALANCE:ultimateDebtor:ITAV/-99917522.270
ITBD Opening balance plus future dated transaction balance (not available to use). /POSTED-BALANCE:ultimateDebtor:ITBD/5705832421.58
TIMESTAMP Timestamp when the balance was recorded in ISO 8601 format. /POSTED-BALANCE:ultimateDebtor:TIMESTAMP/2023-09-19T12:02:29.185+00:00
VERSION Version number of the balance record. /POSTED-BALANCE:ultimateDebtor:VERSION/153
XPCD Ledger balance plus pending credits. /POSTED-BALANCE:ultimateDebtor:XPCD/5705832421.58

Notice of Change

A US ACH Notice of Change (NOC) is a method used to notify a client to correct or change account information in an entry processed through the ACH network. For more information about US ACH, see Send low-value funds through US ACH.

Typically, the Receiving Depository Financial Institution (RDFI) generates the NOC when it identifies incorrect or outdated information in an ACH entry, such as an account number, routing number, or other payment details.

The RDFI sends the NOC to the Originating Financial Depository Institution (ODFI), and as a participant of US ACH clearing, the ODFI is obligated to use the information in the NOC to make necessary updates to prevent repeat NOCs and avoid Nacha fines. (Nacha is a non-profit organization that manages the ACH network.)

When you submit a PayOut or a PayInto Collection using US ACH, if the counterparty's information is incorrect or outdated, you might receive an NOC. NOCs are an important part of maintaining accurate and efficient ACH payment processing in the US.

Example

The following is an example of a notification for a PayOut transaction with one NOC. NOCs are included in the statusReasonInformation.additionalInformation field:

Example notification: PayOut with one NOC
Json
{
    "statusReasonInformation": [
        {
            "additionalInformation": [
                "/eventType/NoticeOfChange",
                "/NOC:account/XXXXXXXXXX",
                "/NOC:receivedDate/2025-02-03",
                "/NOC:reason:code/AG03",
                "/NOC:reason:description/C05 – Incorrect Transaction Code",
                "/NOC:correctedValues[0]:type/TRANSCODE",
                "/NOC:correctedValues[0]:value/37"
            ]
        }
    ]
}

Key points

Here is some important information about NOCs.

  • The NOC provides the correct information that you should use in future transactions.
  • The NOC does not change the amount of the original transaction.
  • NOCs are sent to ensure that future ACH entries are processed correctly and to maintain compliance with Nacha rules.
  • Common reasons for NOCs include incorrect account numbers, routing numbers, transaction codes, and addenda format errors.
  • Each NOC includes a change code that specifies the type of correction needed. For more information, see Change codes.
  • You must make the necessary corrections within a specified timeframe, usually within two business days from the original entry settlement date.
  • NOCs can be accompanied by a return if the issue cannot be resolved, but receiving an NOC does not itself initiate a return.
  • NOC notifications are sent to you with details such as the original transaction reference, change code, and corrected data, allowing you to tie the NOC to the original payment and update your records accordingly.

Delivery methods

You can choose to receive NOCs using either, or both, of the following options:

  • Receive a daily NOC file (Excel) in standard ACH format, using the same transmission method as other Wallet standard reports.
  • Receive a daily NOC message for each transaction with one or more NOCs.

Wallet sends both NOC files and NOC messages on business days, 8-10 AM ET. NOC files and messages provide information about the previous business day. For example, an NOC that you receive on Monday would provide information about a transaction executed on Friday.

To begin receiving daily NOC files and/or messages, contact your J.P. Morgan sales representative.

NOC information

NOC information is presented in notifications as key-value pairs in strings in the following format: /NOC:{key1}:{key2}/{value}

  • NOC: Indicates that this string is related to an NOC.
  • {key1}: Specifies what the value is.
  • {key2}: Optional second key further specifying what the value is.
  • {value}: The actual value.

The following table lists the different keys that might be included in NOC information in notifications.

NOC information
Key Description Example
account Account number of the associated bank account. /NOC:account/XXXXXXXXXX
correctedValues[{index}]:type Type of the corrected value. /NOC:correctedValues[0]:type/TRANSCODE
correctedValues[{index}]:value Corrected value. Replace the original value with this corrected value. /NOC:correctedValues[0]:value/37
reason:code ISO code for the issue in the NOC. For more information, see Change codes. /NOC:reason:code/AG03
reason:description Return code and description of the issue in the NOC. /NOC:reason:description/C05 – Incorrect Transaction Code
receivedDate Date on which the NOC was received. /NOC:receivedDate/2025-02-03

NOC codes

NOCs include codes that help you identify and correct issues. In reason:code, the NOC provides the ISO code; in reason:description, the NOC provides the return code.

The following table lists the commonly used NOC codes that might appear in the Wallet NOC file or notification.

US ACH NOC codes
Return code ISO code Client-facing description Nacha description Client resolution
C01 AC01 C01 - Incorrect DFI Account Number Correct DFI Account Number appears in first 17 positions of the Corrected Data Field. Correct the bank account number (in case the bank account number changed due to a merger or consolidation).
C02 RC01 C02 - Incorrect Routing Number Correct Routing Number (including Check Digit) appears in the first nine positions of the Corrected Data Field. Correct the transit/routing number (in case of merger or consolidation).
C03 NARR C03 - Incorrect Routing Number and Incorrect DFI Account Number Correct Routing Number (including Check Digit) appears in the first nine positions of the Corrected Data Field -- Correct DFI Account Number appears in the 13th through 29th position of same field with a space in the 10th, 11th, and 12th positions. This code is a combination of C01 and C02. Correct the transit/routing and bank account number (in case of merger or consolidation).
C05 NARR C05 - Incorrect Transaction Code Correct Transaction Code appears in first 2 positions of the Corrected Data Field. Correct the bank account type.
C06 AC01 C06 – Incorrect DFI Account Number and Incorrect Transaction Code Correct DFI Account Number appears in first 17 positions of the Corrected Data Field -- correct Transaction Code appears in the 21st and 22nd positions of the same field with spaces in the 18th, 19th, and 20th positions. This code is a combination of C01 and C05. Correct the bank account number (in case the bank account number changed due to a merger or consolidation) and bank account type.
C07 NARR C07 – Incorrect Routing Number, Incorrect DFI Account Number, and Incorrect Transaction Code Correct Routing Number (including check digit) appears in the first 9 positions of the Corrected Data Field – correct DFI Account Number appears in the 10th through 26th positions of the same field – and correct Transaction Code appears in the 27th and 28th positions of the same field. This code is a combination of C01, C02, and C05. Correct the bank account number, transit/routing number (in case of merger or consolidation), and bank account type.
C08 RC04 C08 – Incorrect Receiving DFI Identification (IAT only) The correct Receiving DFI identification appears in the first 34 positions of the Corrected Data Field. Correct the Foreign Receiving DFI Identification number.
C09 BE15 C09 - Incorrect Individual Identification Number, Incorrect Receiver Identification Number Correct Number appears in first 22 positions of the Corrected Data Field. Correct the Individual Identification number.
C13 NARR C13 – Addenda Format Error Information in the Entry Detail Record was correct and the Entry was able to be processed and posted by the RDFI. However, information found in the Addenda Record was unclear or was formatted incorrectly. Information in the Addenda Record was unclear or was not formatted in ANSI- or NACHA-endorsed conventions.

Masking

For security, Wallet can mask sensitive fields (account numbers, names, addresses, IDs) in notifications. When masking is enabled, Wallet replaces sensitive fields with placeholder values (XXXXXXXXXX) so as to not expose the actual data in notifications.

To enabling masking in your Wallet program, contact your J.P. Morgan representative.

The following is an example of a notification with masking enabled.

Example notification: Masking enabled
Json
{
    "debtorAccount": {
        "identification": {
            "other": {
                "identification": "XXXXXXXXXX"
            }
        },
        "currency": "USD"
    },
    "creditorAgent": {
        "financialInstitutionIdentification": {
            "bic": "XXXXXXXXXXX",
            "name": "XXXXXXXX",
            "postalAddress": {
                "country": "US"
            }
        }
    },
    "creditorAccount": {
        "identification": {
            "other": {
                "identification": "XXXXXXXXXX"
            }
        },
        "currency": "USD"
    }
}