# JPMC-PDP Documentation from https://developer.payments.jpmorgan.com # Manage and display transactions Transactions represent the movement of money into and out of an Embedded account. Transactions can be made using: - ACH, wire and RTP payment methods. - 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: **Show transactions table** | Criteria | Field | Details | Pattern & 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, 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": "8dNX612yNkdyKhL2", "transactionReferenceId": "hdsads12334", "originatingId": null, "status": "COMPLETED", "type": "TRANSFER", "originatingTransactionType": null, "ledgerBalance": 30.88, "debtorClientId": "0001002435", "debtorAccountId": "8d5c3da9ec6e492f8e35bc3edfb92942", "debtorAccountNumber": null, "debtorName": "Online Marketplace", "creditorClientId": "1000010400", "creditorAccountId": "d5aaf0db11e747daa2d955806f6eb14e", "creditorAccountNumber": "...0717", "creditorName": "Toy Store", "recipientId": null, "amount": 150.20, "currency": "USD", "paymentDate": "2024-04-22", "createdAt": "2024-04-22T08:36:35.071Z", "postingVersion": 1, "effectiveDate": "2023-04-24" }, { "id": "3ZJUCLKH3c1sIWk", "transactionReferenceId": "2hjsa998931301jkj", "originatingId": null, "status": "COMPLETED", "type": "ACH", "originatingTransactionType": null, "ledgerBalance": 10.00, "debtorClientId": "1000010400", "debtorAccountId": "d5aaf0db11e747daa2d955806f6eb14e", "debtorAccountNumber": "...0717", "debtorName": "Toy Store", "creditorClientId": null, "creditorAccountId": null, "creditorAccountNumber": "...9492", "creditorName": "Monica Gellar", "recipientId": "d9dab78e-e366-4dde-ac9d-fb3f9d48437b", "amount": 20.88, "currency": "USD", "paymentDate": "2024-04-23", "createdAt": "2024-04-23T17:15:12.761Z", "postingVersion": 2, "effectiveDate": "2024-04-24", "memo": "Invoice 1234" }, { "id": "DF23CLKH3c1sHJG", "transactionReferenceId": "Ajsa99893130er45", "originatingId": null, "status": "REJECTED", "type": "ACH", "originatingTransactionType": null, "ledgerBalance": 10.00, "debtorClientId": "1000010400", "debtorAccountId": "d5aaf0db11e747daa2d955806f6eb14e", "debtorAccountNumber": "...0717", "debtorName": "Toy Store", "creditorClientId": null, "creditorAccountId": null, "creditorAccountNumber": "...9492", "creditorName": "Monica Gellar", "recipientId": "d9dab78e-e366-4dde-ac9d-fb3f9d48437b", "amount": 11.23, "currency": "USD", "paymentDate": "2024-04-23", "createdAt": "2024-04-23T18:15:12.761Z", "postingVersion": 3, "effectiveDate": "2024-04-24" }, { "id": "89JUCLKH3c1sIWk", "transactionReferenceId": null, "originatingId": "3ZJUCLKH3c1sIWk", "status": "COMPLETED", "type": "RETURN", "originatingTransactionType": "ACH_PAYOUT", "ledgerBalance": 30.88, "debtorClientId": null, "debtorAccountId": null, "debtorAccountNumber": "...9492", "debtorName": "Monica Gellar", "creditorClientId": "1000010400", "creditorAccountId": "d5aaf0db11e747daa2d955806f6eb14e", "creditorAccountNumber": "...0717", "creditorName": "Toy Store", "amount": 20.88, "currency": "USD", "paymentDate": "2024-04-25", "createdAt": "2024-04-25T19:15:12.761Z", "postingVersion": 1, "effectiveDate": "2024-04-26" } ] } ``` ## 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 { "id": "AqH2mcRStZI06GEo", "transactionReferenceId": "Lfi9QVmuXpawZ817", "originatingId": null, "status": "COMPLETED", "type": "ACH", "originatingTransactionType": null, "ledgerBalance": 10000, "debtorClientId": "1000010400", "debtorAccountId": "d5aaf0db11e747daa2d955806f6eb14e", "debtorAccountNumber": "...0717", "debtorName": "Toy Store", "creditorClientId": null, "creditorAccountId": null, "creditorAccountNumber": "...9492", "creditorName": "Monica Gellar", "recipientId": "d9dab78e-e366-4dde-ac9d-fb3f9d48437b", "amount": 15.30, "currency": "USD", "paymentDate": "2024-04-23", "createdAt": "2024-04-23T17:10:13.512Z", "postingVersion": 1, "effectiveDate": "2024-04-24" } ``` 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: - effectiveDate - 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 `effectiveDate` 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, "effectiveDate": "2024-04-29", "postingVersion": 2, "ledgerBalance": 384.40, ... }, { "id": "aZdD75NoFq1v7cpI", "amount": 25.08, "effectiveDate": "2024-04-29", "postingVersion": 5, "ledgerBalance": 359.32, ... }, { "id": "nmerFJXJQBqDvbd4", "amount": 50.10, "effectiveDate": "2024-04-28", "postingVersion": 15, "ledgerBalance" 489.90, ... } { "id": "87dRZmt2v6wINrV1", "amount": 100, "effectiveDate": "2024-04-29", "postingVersion": 1, "ledgerBalance": 389.90, ... } ] ``` Here is how these transactions should be ordered using effectiveDate, 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, like `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. 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.