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
https://developer.moneybird.com/api/sales_invoices/#get_sales_invoices
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