In addition to @Dennis Snijder I will try to explain why the need for looking up a Payment (for example by description) is something that occurs often and why fetching and iterating the Payments on the user side is a sub-optimal approach.
Suppose a BankAccount processes on average 50 transactions every weekday (Monday to Friday). Then a user wants to look up a Payment with a description for which he knows is unique: "XYZ.XYZ". For example: a Mollie Settlement has such a unique description which they call "reference": https://www.mollie.com/en/docs/reference/settlements/list#parameters
In case all Payments of the last month should be considered this would mean fetching (5 * 50 * 4) = 1000 Payments and then iterating them. Suppose we / our software is looking for a Mollie Settlement of 6 months ago, this would mean iterating 6000 Payments, just to find a Payment for which we "know" the description is unique. Seems a bit silly...
I hope I explained a viable use case of why the API should have improved support for querying / filtering Payments.
I would recommend to have a look on how MoneyBird offers this functionality using filters and specific findByXYZ methods
Next to "looking up by description", some other scenarios that could be imagined as being useful when communicating with the API to automate business processes:
- lookup by Payment target IBAN
- lookup by Payment.merchantReference