# JPMC-PDP Documentation from https://developer.payments.jpmorgan.com

# View and display transactions

Transactions represent the movement of money into and out of an Embedded account. Transactions can be made using:

- Automated Clearing House (ACH), wire transfer, Real-Time Payments (RTP) and Push to Card (P2C).

- Transfers between your and your clients' Embedded Payments accounts.

- Transfers to your JPMC DDA (Demand Deposit Account) Treasury account are related to Client Introduction Compensation and FX (Foreign Exchange) Spread Client Markup, if applicable.

You can create a transactions experience to show a list of details about transactions on your client's account.

You can provide filters to help the user navigate their transactions using the `GET /transactions `request.

## Show transactions

You can return all transaction history available by sending an empty object in the request to `GET /transactions`. You can further refine the transactions returned with the following filter properties in your GET request body:

 
**You can further refine the transactions returned with the following filter properties in your GET request body**

| Criteria | Field | Details | Pattern and example | 
| --- | --- | --- | --- | 
| Client Id | clientId | String. Filters by the Embedded finance client ID | ^\d{10}$ 1000010400 | 
| Account ID | accountId | String. Filters by the Embedded account ID connected to the transaction. | d5aaf0db11e747daa2d955806f6eb14e | 
| Exact amount | amountEquals | String. Numerical entries only. Does not require currency. Follows decimal values of dollars and cents. Returns results that match to an exact amount. | ^\d{0,15}(?:[.]\d{1,2})?$ 5009.23 | 
| More than an amount | amountGreaterThan | String. Numerical entries only. Does not require currency. Follows decimal values of dollars and cents. Returns transactions with an amount greater than the supplied number. | ^\d{0,15}(?:[.]\d{1,2})?$ 5000.00 or 5000 | 
| Less than an amount | amountLessThan | String. Numerical values. Does not require currency. Returns transactions with an amount less than the supplied number. | ^\d{0,15}(?:[.]\d{1,2})?$ 4000.00 or 4000 | 
| On a specific date | dateEquals | String. A date in the format yyyy-mm-dd. Returns all transactions on a specific date. | `^\d{4}-(0[1-9] | 
| After a specific date | dateGreaterThan | String. A date in the format YYYY-MM-DD. Returns all transactions after a specific date. | `^\d{4}-(0[1-9] | 
| Before a specific date | dateLessThan | String. A date in the format YYYY-MM-DD. Returns all transactions before a specific date. | `^\d{4}-(0[1-9] | 
| Transaction type | type | Enum. Returns all transactions that were paid out, captured as a hold on a pending transaction (such as online payments that are not settled until delivery), or paid into the account. | ACH, WIRE, RTP, CARD, TRANSFER, REVERSAL, RETURN, OTHER. | 
| Recipient | recipientId | String. Returns all transactions for a specific recipient. | d9dab78e-e366-4dde-ac9d-fb3f9d48437b | 
| Status | status | String. Returns all transactions with a specified transaction status. Must match a valid status value. | PENDING - The transaction is still being processed. CANCELED - The transaction has been canceled. COMPLETED - The transaction has been completed. COMPLETED_WITH_EXCEPTIONS - The transaction has completed, but not all of the requested criteria has been fulfilled. REJECTED - The transaction has been rejected and will not be completed. RETURNED - The payment rail has been unable to complete the payment specified recipient. The payment has been returned to the originator. PARTIALLY_COMPLETED - Not all transactions in the batch have been completed. UNDEFINED - The status of this transaction cannot be found. | 

Response example for an open, unfiltered `GET /transactions` request:

```json
{
  "metadata": {
    "page": 0,
    "limit": 4,
    "total_items": 4
  },
  "items": [
    {
      "id": "41nSnW9dI",
      "transactionReferenceId": "rO4u6Rd3R",
      "status": "REJECTED",
      "type": "ACH",
      "requestedExecutionDate": "2026-01-02",
      "localInstrumentCode": "CCD",
      "memo": "REMITTANCE INFORATION OF FIRST PAYMENT IN THE IDDT BATCH",
      "amount": "5.0E+11",
      "currency": "USD",
      "debtor": {
        "partyDetails": {
          "name": "HERBLIFE"
        },
        "account": {
          "type": "NOT_APPLICABLE",
          "externalAccount": {
            "number": "...8800"
          }
        }
      },
      "creditor": {
        "clientId": "1000014199",
        "partyDetails": {
          "name": "EWALLET RECEIVER"
        },
        "account": {
          "type": "REGISTERED_ACCOUNT",
          "registeredAccount": {
            "id": "c3a9b877ab4647e6a9eff2cfd7ee6764",
            "number": "...0794"
          }
        }
      }
    },
    {
      "id": "4BlYcoqThT",
      "transactionReferenceId": "",
      "status": "REJECTED",
      "type": "WIRE",
      "requestedExecutionDate": "2026-01-02",
      "localInstrumentCode": "",
      "memo": "This is the remittance information",
      "amount": "5.0E+11",
      "currency": "USD",
      "targetAmount": "5.0E+11",
      "targetCurrency": "MXN",
      "debtor": {
        "clientId": "1000014199",
        "partyDetails": {
          "name": "ewallet"
        },
        "account": {
          "type": "REGISTERED_ACCOUNT",
          "registeredAccount": {
            "id": "c3a9b877ab4647e6a9eff2cfd7ee6764",
            "number": "...0794"
          }
        }
      },
      "creditor": {
        "partyDetails": {
          "name": "ewallet creditor"
        },
        "account": {
          "type": "NOT_APPLICABLE",
          "externalAccount": {
            "number": "...4120"
          }
        }
      }
    },
    {
      "id": "dSMQaUyBJZ",
      "transactionReferenceId": "",
      "status": "REJECTED",
      "type": "WIRE",
      "requestedExecutionDate": "2026-01-02",
      "localInstrumentCode": "",
      "memo": "This is the remittance information",
      "amount": "5.0E+11",
      "currency": "USD",
      "debtor": {
        "clientId": "1000014199",
        "partyDetails": {
          "name": "ewallet"
        },
        "account": {
          "type": "REGISTERED_ACCOUNT",
          "registeredAccount": {
            "id": "c3a9b877ab4647e6a9eff2cfd7ee6764",
            "number": "...0794"
          }
        }
      },
      "creditor": {
        "partyDetails": {
          "name": "ewallet creditor"
        },
        "account": {
          "type": "NOT_APPLICABLE",
          "externalAccount": {
            "number": "...4303"
          }
        }
      }
    },
    {
      "id": "OPQFCn7rpJ",
      "transactionReferenceId": "2vMmP0j8PePeQ5uj6GEprssAAp",
      "status": "REJECTED",
      "type": "WIRE",
      "requestedExecutionDate": "2026-01-02",
      "localInstrumentCode": "",
      "memo": "M E716712 C U254944 MADEELLED TO TEST REMITTANCE INFORMATION MAXD CHARACTERS",
      "amount": "5.0E+11",
      "currency": "USD",
      "debtor": {
        "clientId": "1000014199",
        "partyDetails": {
          "name": "EWALLET ORIGINATOR"
        },
        "account": {
          "type": "REGISTERED_ACCOUNT",
          "registeredAccount": {
            "id": "c3a9b877ab4647e6a9eff2cfd7ee6764",
            "number": "...0794"
          }
        }
      },
      "creditor": {
        "partyDetails": {
          "name": "MAYBANK"
        },
        "account": {
          "type": "NOT_APPLICABLE",
          "externalAccount": {
            "number": "...4303"
          }
        }
      }
    }
  ]
}
```

## Organize transaction results

You can choose how to show the results of a transaction request.

Common use cases are:

- Showing payments in and payments out.

- Show the balance after a transaction has completed.

- Showing a running balance including pending transactions.

### Show payments into and out of an account

To show results for all transactions, highlighting payments in and out:

1. Send a GET /transactions request with no filters in the request body.

2. For every transaction item with a creditorAccountId value that matches your client's account, you can show as a payment into this account.

3. For every other transaction item, you can show as a payment going out of this account.

### Show a running balance

As your user's transactions are processed, you can provide a running balance alongside each transaction - this shows the balance after the transaction has cleared.

The ledger balance of an account represents all completed transactions. You can display this total using the `ledgerBalance` property returned in a `GET /transactions` request.

In the example below, the result of this completed transaction is that the balance of the ledger is now $10000. As more transactions are completed, this balance will change to reflect subsequent updates to the ledger:

```json
{
  "metadata": {
    "page": 0,
    "limit": 4,
    "total_items": 4
  },
  "items": [
    {
      "id": "41nSnW9dI",
      "transactionReferenceId": "rO4u6Rd3R",
      "status": "REJECTED",
      "type": "ACH",
      "requestedExecutionDate": "2026-01-02",
      "localInstrumentCode": "CCD",
      "memo": "REMITTANCE INFORATION OF FIRST PAYMENT IN THE IDDT BATCH",
      "amount": "5.0E+11",
      "currency": "USD",
      "debtor": {
        "partyDetails": {
          "name": "HERBLIFE"
        },
        "account": {
          "type": "NOT_APPLICABLE",
          "externalAccount": {
            "number": "...8800"
          }
        }
      },
      "creditor": {
        "clientId": "1000014199",
        "partyDetails": {
          "name": "EWALLET RECEIVER"
        },
        "account": {
          "type": "REGISTERED_ACCOUNT",
          "registeredAccount": {
            "id": "c3a9b877ab4647e6a9eff2cfd7ee6764",
            "number": "...0794"
          }
        }
      }
    },
    {
      "id": "4BlYcoqThT",
      "transactionReferenceId": "",
      "status": "REJECTED",
      "type": "WIRE",
      "requestedExecutionDate": "2026-01-02",
      "localInstrumentCode": "",
      "memo": "This is the remittance information",
      "amount": "5.0E+11",
      "currency": "USD",
      "targetAmount": "5.0E+11",
      "targetCurrency": "MXN",
      "debtor": {
        "clientId": "1000014199",
        "partyDetails": {
          "name": "ewallet"
        },
        "account": {
          "type": "REGISTERED_ACCOUNT",
          "registeredAccount": {
            "id": "c3a9b877ab4647e6a9eff2cfd7ee6764",
            "number": "...0794"
          }
        }
      },
      "creditor": {
        "partyDetails": {
          "name": "ewallet creditor"
        },
        "account": {
          "type": "NOT_APPLICABLE",
          "externalAccount": {
            "number": "...4120"
          }
        }
      }
    },
    {
      "id": "dSMQaUyBJZ",
      "transactionReferenceId": "",
      "status": "REJECTED",
      "type": "WIRE",
      "requestedExecutionDate": "2026-01-02",
      "localInstrumentCode": "",
      "memo": "This is the remittance information",
      "amount": "5.0E+11",
      "currency": "USD",
      "debtor": {
        "clientId": "1000014199",
        "partyDetails": {
          "name": "ewallet"
        },
        "account": {
          "type": "REGISTERED_ACCOUNT",
          "registeredAccount": {
            "id": "c3a9b877ab4647e6a9eff2cfd7ee6764",
            "number": "...0794"
          }
        }
      },
      "creditor": {
        "partyDetails": {
          "name": "ewallet creditor"
        },
        "account": {
          "type": "NOT_APPLICABLE",
          "externalAccount": {
            "number": "...4303"
          }
        }
      }
    },
    {
      "id": "OPQFCn7rpJ",
      "transactionReferenceId": "2vMmP0j8PePeQ5uj6GEprssAAp",
      "status": "REJECTED",
      "type": "WIRE",
      "requestedExecutionDate": "2026-01-02",
      "localInstrumentCode": "",
      "memo": "M E716712 C U254944 MADEELLED TO TEST REMITTANCE INFORMATION MAXD CHARACTERS",
      "amount": "5.0E+11",
      "currency": "USD",
      "debtor": {
        "clientId": "1000014199",
        "partyDetails": {
          "name": "EWALLET ORIGINATOR"
        },
        "account": {
          "type": "REGISTERED_ACCOUNT",
          "registeredAccount": {
            "id": "c3a9b877ab4647e6a9eff2cfd7ee6764",
            "number": "...0794"
          }
        }
      },
      "creditor": {
        "partyDetails": {
          "name": "MAYBANK"
        },
        "account": {
          "type": "NOT_APPLICABLE",
          "externalAccount": {
            "number": "...4303"
          }
        }
      }
    }
  ]
}
```

If you want to show the transactions in the order that they affected the ledger balance then you need to use two fields together to sort the transactions:

- valueDate - The date on which the transaction completed (and therefore increased/decreased the ledger balance).

- postingVersion - The order on which transactions were posted to the ledger on a given day. The highest value represents the most recent posting.

You can use these details to sort the transactions such that `valueDate` and `postingVersion` are descending, then the transactions are ordered in the order they affected the ledger balance.

The `ledgerBalance` shows the account's running balance over time.

### Example of ordering transactions

Take a look the following transactions. Each item has been stripped back to show only the most important information for ordering:

```json
[
  {
    "id": "2YBRjo1NMao1Gx9T",
    "amount": 5.50,
    "valueDate": "2024-04-29",
    "postingVersion": 2,
    "ledgerBalance": 384.40,
    ...
  },
  {
    "id": "aZdD75NoFq1v7cpI",
    "amount": 25.08,
    "valueDate": "2024-04-29",
    "postingVersion": 5,
    "ledgerBalance": 359.32,
    ...
  },
  {
    "id": "nmerFJXJQBqDvbd4",
    "amount": 50.10,
    "valueDate": "2024-04-28",
    "postingVersion": 15,
    "ledgerBalance": 489.90,
    ...
  }
  {
    "id": "87dRZmt2v6wINrV1",
    "amount": 100,
    "valueDate": "2024-04-29",
    "postingVersion": 1,
    "ledgerBalance": 389.90,
    ...
  }
]
```

Here is how these transactions should be ordered using `valueDate`, `postingVersion` and `ledgerBalance`:

 
**Ordering transactions table**

| Transaction ID | Amount | Ledger Balance | Effective Date | Posting Version | 
| --- | --- | --- | --- | --- | 
| aZdD75NoFq1v7cpI | 25.08 | 359.32 | 2024-04-29 | 5 | 
| 2YBRjo1NMao1Gx9T | 5.50 | 384.40 | 2024-04-29 | 2 | 
| 87dRZmt2v6wINrV1 | 100 | 389.90 | 2024-04-29 | 1 | 
| nmerFJXJQBqDvbd4 | 50.10 | 489.90 | 2024-04-28 | 15 | 

### Use transaction ordering to show transactions and balance over a fixed period of time

Use a date range to limit the transactions you want to list. Using transactions ordering within a date range, you can give a snapshot of a specific period of time.

To add an opening and closing balance for a period, you can use the `ledgerBalance` of the **first** transaction as the opening balance for the period, and the `ledgerBalance`** **of the **last **transaction as the closing balance for the period. 

## Understanding transaction types and transaction status

You can present transactions to your users with information about their `type` - the nature of the transaction, and their `status` - the stage a transaction has reached in the process.

When presenting transactions to your user, keep in mind that a `type` usually doesn't change. A `status` changes over time until it reaches its final state, such as `COMPLETE`, and is recorded in the ledger.

### Transaction types

The `type` properties and their meaning:

- TRANSFER: Funds have been moved from one account to another within the same Embedded Payments profile. This includes Client Introduction Compensation and FX (Foreign Exchange) Spread Client Markup.

- ACH: Funds have been moved out of or into the user's account via ACH.

- WIRE: Funds have been moved out of or into the user's account via wire.

- RTP: Funds have been moved out of or into the user's account via RTP.

- CARD: Funds have been moved out of or into the user's account via P2C.

The status properties and their meaning:

- PENDING: Funds have not yet been transferred, but a request to do so has been successful. This transaction status is normally seen when a payment has only just been made.

- CANCELED: The transaction has been cancelled. Funds have not left the account. This is usually a final status in most cases. A payment cannot be uncanceled.

- COMPLETED: The transaction has been completed. The ledger has been updated. This is usually a final status for a transaction.

- COMPLETED_WITH_EXCEPTIONS: The transaction is complete, but some elements of the process have not worked as expected. For example, there may have been a minor error that stopped a transactionType being assigned. However, the transaction itself is completed and the funds have been moved.

- REJECTED: The transaction request has been rejected. This is usually because of a banking issue, for example the recipient of the payment could not be reached, or funds were not adequate to complete the transaction.

- RETURNED: A payment has been returned after a transaction has been completed.

- PARTIALLY-COMPLETED: Not all transactions in the batch have been completed.

- UNDEFINED: It was not possible to assign a status to the transaction.