List scheduled debits
Returns the payer’s scheduled-debit lifecycle for the account — the “consulta e gerenciamento de pagamentos agendados” of Guia v1.2 §6.4.
It is NOT a forward-only view: a debit stays listed after it leaves SCHEDULED, so CANCELLED entries appear beside the ones still to come. A payer asking why a charge did not happen needs the cancelled row, and the cancellation route needs the id only this listing returns.
The status keeps the scheduling lifecycle and does NOT report the payment: a debit that settled keeps reading SCHEDULED. The settlement carries the payment outcome, read from the debit’s LATEST settlement attempt — outcome PROCESSING while the order is in flight, COMPLETED once the money moved, REJECTED (with failureCategory when a cause was recorded) or UNKNOWN when the order was dispatched and its fate is not yet known — together with the attempt’s endToEndId, startedAt and, once COMPLETED or REJECTED, concludedAt. settlement is absent while the debit has no attempt. When a read replica is configured, an attempt that has just concluded can still read PROCESSING for a moment; Get scheduled payment reads the primary database. The settlement_* events push only negative or pending outcomes; a COMPLETED settlement emits no event and is seen only by re-reading this listing (or the account’s outgoing Pix).
On a request without a cursor, an empty page means that no scheduled debit of the account named in X-Account-Id matched the query (with no filter, the account has none). On a later page it means only that no matching debit remains past the cursor.
This is the ONLY operation that returns a scheduled debit’s id, and POST /v1/payer/scheduled-payments//cancel needs that id. Integrate the two together: list, then cancel by the id an item carries.
Each item carries maximumAmountSnapshot — the ceiling in force when the debit was SCHEDULED, written once and never updated — so a payer who has since changed the ceiling can see why an existing debit still reflects the old one. Returning it here is the payer’s own authenticated channel; Guia v1.2 §6.1 bars sharing it with the RECEIVING user and their PSP, which this surface is not.
Each item also carries, from the moment the debit is scheduled, its top-level endToEndId, the end-to-end identifier the debit settles under, and its receiver (name and CPF or CNPJ). On a debit scheduled from the payment instruction of the receiving PSP (pain.013), the endToEndId is the one that PSP minted, and it equals settlement.endToEndId once an attempt exists. On a debit scheduled from an Open Finance payment initiation, it is the endToEndId that the initiator sent. Both fields are omitted, not empty, when they are not available.
Ordering is by scheduledDate and then by id, which is also what the cursor resumes on — not the write instant, unlike the three sibling listings. authorizationId is absent on a debit scheduled without a mandate (purpose RIFL), and maximumAmountSnapshot is absent when no ceiling was in force; neither absence is an error.
Four optional filters narrow the page, each combined with the account in X-Account-Id: status (comma-separated in one parameter, for example status=SCHEDULED,CANCELLED; an unknown value matches no row), authorization_id (the debits of one mandate), and start_date and end_date (YYYY-MM-DD, both inclusive, bounding scheduledDate rather than the creation instant). A malformed authorization_id or date, or an end_date earlier than start_date, is answered 400 PIX-0003 naming the field. Only SCHEDULED and CANCELLED are produced, and a settled debit keeps reading SCHEDULED, so read settlement.outcome for the payment result.
Paging is by cursor. On the last page next_cursor is null, never an empty string.
Autorizações
JWT bearer token issued by the identity provider.
Cabeçalhos
Non-zero UUID of the payer account selected by the calling PSP. The PSP must authorize its end user for that account before calling this API. A resource outside the selected account returns 404; a read with no records returns an empty page. See the API overview for the complete trust boundary.
^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$Parâmetros de consulta
Maximum number of records per page (1-100, default 10). A value outside that range, or one that is not an integer, is REFUSED — never clamped, never silently coerced.
1 <= x <= 100Opaque cursor taken from a previous page's next_cursor. On the last page that value is null, never an empty string. A malformed or undecodable value is refused with 400. The cursor must be replayed against the same endpoint, with the same sort_order and the same filters used to obtain it; changing any of those starts a different query, and the previous cursor should not be reused.
"eyJ0IjoiMjAyNi0wOC0yN1QxODo0MjowMFoiLCJpIjoiMDE5OGYzYTEtN2M0Mi03ZGUxLWEwMjQtYjFmMGI3ZTljMzAxIn0="
Sort direction. An unrecognised value is refused rather than silently defaulted, because switching it mid-traversal without notice would silently reverse the page sequence the caller is walking.
asc, desc "desc"
Filter by the DEBIT's status, the vocabulary each item's status field carries: SCHEDULED, DISPATCHING, SETTLED, FAILED, CANCELLED, RECONCILING. To filter on several, send them as ONE comma-separated value (status=SCHEDULED,CANCELLED): repeating the parameter is not supported, and only its first occurrence is read. A status this end does not know matches no row, which is an empty page rather than an error. Only SCHEDULED and CANCELLED are produced today, and a debit that SETTLED keeps reading SCHEDULED: filter on status for the scheduling lifecycle and read settlement.outcome for the payment result.
Only the debits scheduled under this mandate (the id of GET /v1/payer/authorizations). A debit with no mandate (a RIFL resend, or one scheduled from an Open Finance payment initiation) never matches. A mandate of another account matches nothing: the account in X-Account-Id still scopes the page. A value that is not a UUID is answered 400 PIX-0003 naming authorization_id.
"01a044a8-f3bd-7488-a0dc-e8d4be4802be"
Earliest scheduledDate to include, INCLUSIVE, as a calendar date YYYY-MM-DD. It bounds the settlement date, not the creation instant. A malformed date is answered 400 PIX-0003 naming start_date.
"2026-09-01"
Latest scheduledDate to include, INCLUSIVE, as a calendar date YYYY-MM-DD. A malformed date is answered 400 PIX-0003 naming end_date, and so is an end_date earlier than start_date. There is no maximum range.
"2026-09-30"
Resposta
A page of scheduled debits, newest settlement date first. Empty when the account named in X-Account-Id has none.
Empty array when there are no results, never null. On a request without a cursor, an empty array means that no scheduled debit of the account named in X-Account-Id matched the query; on a later page, it means only that no match remains past the cursor.
Opaque cursor for the next page. NULL on the last page, never an empty string.
"eyJ0IjoiMjAyNi0wOC0yN1QxODo0MjowMFoiLCJpIjoiMDE5OGYzYTEtN2M0Mi03ZGUxLWEwMjQtYjFmMGI3ZTljMzAxIn0="
Opaque cursor for the previous page. These listings do not issue a backwards cursor, so the value is null.