Query API

A query API is the part of a payment platform a system talks to when it wants to read something, not change it. It answers questions: what happened to this payment, which payments settled yesterday, what is the balance on this account, show me every refund in March. Nothing moves as a result. The call goes out, data comes back, and the state of the world is the same as it was before, which is the property that makes these calls safe to repeat.

That read-only quality is the whole design. An API that takes money has to worry about a request arriving twice. A query API does not, and the standard that draws the line, RFC 9110 on HTTP semantics, calls such methods safe. In payments the upshot is that a finance system can poll a query endpoint as often as it needs to, with nobody worrying about a double charge. It is the least showy part of a build, and often where a team spends most of its time.

Four Questions It Gets Asked

Four kinds of question cover most real traffic. The state of one payment, usually by transaction ID. A list of payments over a date range, for the finance team. Settlement and fee data, so the money that arrived can be tied to the sales that caused it. And reference data such as accepted methods or currency support. Each has a different shape and a different volume, and a platform that serves the first well can still serve the second badly.

Filtering, Paging And Sorting

A list endpoint is only useful if it can be narrowed. The usual controls are a filter, a field choice, a sort order and a way to page through results. There is a published grammar for all of them, and the OASIS OData URL conventions define options such as filter, select, top and skip. Not every payment platform follows the OData standard, and the ones that invent their own grammar each do it a different way. Paging is where most builds break, because a naive loop over page numbers drops rows when new records arrive mid-scan.

Polling Or Being Told

A query API answers when asked, which means someone has to ask. The other route is being told, and that is what a webhook call does. Most working setups use both, since a webhook gives the fast path and a query call gives the truth. Where a webhook is missed, dropped or arrives out of order, a scheduled query is what finds the gap, so treating the two as competing designs is a common and costly mistake.

Reading Money, Not Just Payments

Sales data and settled money are different questions, and a good query API answers both. Payment records tell a business what customers did. A settlement file tells it what actually arrived, net of fees, on which day. Pulling both and posting them against the accounting ledger is the whole of automatic matching, and this piece on matching payments across providers explains why the numbers so often fail to tie out.

Limits, Quotas And Being A Good Client

Query endpoints are cheap to call and easy to abuse, so providers throttle them. A rate limit is normal, and a business should design for it instead of meeting it during a month-end run. The usual habits are simple: page rather than pull everything, filter at the provider and not in your own code, cache what does not change, and back off when a limit is hit. A nightly job that asks for the whole year every time will in the end be the reason a limit gets tightened.

People Read It Too

People need this data as well as machines. A merchant dashboard is usually a query API with a face on it, and the two should agree. A support agent quoting one figure while the finance export says another is a hard call to take. Where a provider ships a client SDK, it normally wraps the same endpoints and saves a team writing paging and retry logic from scratch.

Data Protection Applies Here Too

A query API hands out personal and financial data, which earns it the same care as any endpoint that moves money. Access belongs behind proper credentials, with scopes narrow enough that a reporting key cannot read the lot. Responses should carry only the fields the caller needs. Where a provider handles personal data on a business's behalf, a data processing agreement sets out the terms, and what the law requires differs by market.

Testing Before It Matters

Query bugs are quiet. A paging error does not throw an exception. It just returns fewer rows than it should, and nobody notices until a month does not balance. So the tests worth writing are the awkward ones: a range that spans a page boundary, a range with no results, a scan while new records are being written, and a repeat of the same call to confirm the answer holds. Running those in user acceptance testing is far cheaper than finding them in a quarter-end close.

Building It To Last

Pull by reference where you can, and by date range only when you have to. Page properly, with a cursor in place of an offset if the provider offers one. Store the provider's own ids against your records so a later query has something to match on. Schedule a checking query even where webhooks work, because they will not every time. Respect the rate limit by design. And test the boundary cases before go-live. This piece on API-first infrastructure covers the wider shift. Payment analytics is designed to help turn that data into something a team can act on.

‍