List scheduled debits

curl --request GET \
  --url https://api.example.com/pixauto/v1/payer/scheduled-payments \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Account-Id: <x-account-id>'

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/pixauto/v1/payer/scheduled-payments"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Account-Id", "<x-account-id>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'GET',
  headers: {'X-Account-Id': '<x-account-id>', Authorization: 'Bearer <token>'}
};

fetch('https://api.example.com/pixauto/v1/payer/scheduled-payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/pixauto/v1/payer/scheduled-payments"

headers = {
    "X-Account-Id": "<x-account-id>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "items": [
    {
      "amount": "149.90",
      "createdAt": "2026-09-01T12:00:00Z",
      "id": "0198f3a2-1c4e-7c8b-9d1e-2f3a4b5c6d40",
      "purpose": "AGND",
      "recurrenceId": "RN12345678202608101a2b3c4d5e6",
      "scheduledDate": "2026-09-10",
      "status": "SCHEDULED",
      "updatedAt": "2026-09-01T12:00:00Z"
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNi0wOS0xMCIsImkiOiIwMTk4ZjNhMi0xYzRlLTdjOGItOWQxZS0yZjNhNGI1YzZkNDAifQ==",
  "prev_cursor": null
}

{
  "code": "PIX-0142",
  "message": "claim_id is required",
  "title": "Invalid Claim Request",
  "fields": {},
  "headers": {},
  "paths": {},
  "query_params": {},
  "raw": {
    "message": "upstream provider returned 503",
    "status": 123
  }
}

{
  "code": "PIX-0004",
  "message": "Invalid or expired authentication credentials.",
  "title": "Unauthorized"
}

{
  "code": "PIX-0005",
  "message": "You do not have permission to perform this operation.",
  "title": "Forbidden"
}

{
  "code": "PIX-0000",
  "message": "The server encountered an unexpected error. Please try again later.",
  "title": "Internal Server Error"
}

{
  "code": "PIX-0142",
  "message": "claim_id is required",
  "title": "Invalid Claim Request",
  "fields": {},
  "headers": {},
  "paths": {},
  "query_params": {},
  "raw": {
    "message": "upstream provider returned 503",
    "status": 123
  }
}

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 SETTLED and 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.

An empty page means that the account named in X-Account-Id has no scheduled debit.

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.

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.

Paging is by cursor. On the last page next_cursor is null, never an empty string.

GET

payer

scheduled-payments

List scheduled debits

curl --request GET \
  --url https://api.example.com/pixauto/v1/payer/scheduled-payments \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Account-Id: <x-account-id>'

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/pixauto/v1/payer/scheduled-payments"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Account-Id", "<x-account-id>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'GET',
  headers: {'X-Account-Id': '<x-account-id>', Authorization: 'Bearer <token>'}
};

fetch('https://api.example.com/pixauto/v1/payer/scheduled-payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/pixauto/v1/payer/scheduled-payments"

headers = {
    "X-Account-Id": "<x-account-id>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "items": [
    {
      "amount": "149.90",
      "createdAt": "2026-09-01T12:00:00Z",
      "id": "0198f3a2-1c4e-7c8b-9d1e-2f3a4b5c6d40",
      "purpose": "AGND",
      "recurrenceId": "RN12345678202608101a2b3c4d5e6",
      "scheduledDate": "2026-09-10",
      "status": "SCHEDULED",
      "updatedAt": "2026-09-01T12:00:00Z"
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNi0wOS0xMCIsImkiOiIwMTk4ZjNhMi0xYzRlLTdjOGItOWQxZS0yZjNhNGI1YzZkNDAifQ==",
  "prev_cursor": null
}

{
  "code": "PIX-0142",
  "message": "claim_id is required",
  "title": "Invalid Claim Request",
  "fields": {},
  "headers": {},
  "paths": {},
  "query_params": {},
  "raw": {
    "message": "upstream provider returned 503",
    "status": 123
  }
}

{
  "code": "PIX-0004",
  "message": "Invalid or expired authentication credentials.",
  "title": "Unauthorized"
}

{
  "code": "PIX-0005",
  "message": "You do not have permission to perform this operation.",
  "title": "Forbidden"
}

{
  "code": "PIX-0000",
  "message": "The server encountered an unexpected error. Please try again later.",
  "title": "Internal Server Error"
}

{
  "code": "PIX-0142",
  "message": "claim_id is required",
  "title": "Invalid Claim Request",
  "fields": {},
  "headers": {},
  "paths": {},
  "query_params": {},
  "raw": {
    "message": "upstream provider returned 503",
    "status": 123
  }
}

Authorizations

Authorization

string

header

required

JWT bearer token issued by the identity provider.

Headers

X-Account-Id

string<uuid>

required

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.

Pattern: ^[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}$

Query Parameters

limit

integer<int64>

default:10

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.

Required range: 1 <= x <= 100

cursor

string

Opaque 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.

Example:

"eyJ0IjoiMjAyNi0wOC0yN1QxODo0MjowMFoiLCJpIjoiMDE5OGYzYTEtN2M0Mi03ZGUxLWEwMjQtYjFmMGI3ZTljMzAxIn0="

sort_order

enum<string>

default:desc

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.

Available options:

asc,

desc

Example:

"desc"

Response

A page of scheduled debits, newest settlement date first. Empty when the account named in X-Account-Id has none.

items

object[]

required

Empty array when there are no results — never null. An empty array means the account named in X-Account-Id has no scheduled debit.

Show child attributes

next_cursor

string | null

required

Opaque cursor for the next page. NULL on the last page, never an empty string.

Example:

"eyJ0IjoiMjAyNi0wOC0yN1QxODo0MjowMFoiLCJpIjoiMDE5OGYzYTEtN2M0Mi03ZGUxLWEwMjQtYjFmMGI3ZTljMzAxIn0="

prev_cursor

string | null

required

Opaque cursor for the previous page. These listings do not issue a backwards cursor, so the value is null.

DICT and Pix keys

Collections and BR Codes

Payments and refunds

Pix Automático API

Error handling

List scheduled debits

Authorizations

Headers

Query Parameters

Response