List the state transitions of an authorization

curl --request GET \
  --url https://api.example.com/pixauto/v1/payer/authorizations/{authorization_id}/history \
  --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/authorizations/{authorization_id}/history"

	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/authorizations/{authorization_id}/history', 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/authorizations/{authorization_id}/history"

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

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

print(response.text)

{
  "items": [
    {
      "actor": "PAYER",
      "id": "01a044a8-f3bd-7d16-b8d9-6a5cf0319996",
      "newStatus": "AWAITING_CONCLUSION",
      "occurredAt": "2026-08-27T19:18:38Z"
    },
    {
      "actor": "RECEIVER_PSP",
      "id": "01a044a8-f4d6-76a1-aa32-a732ac2e8023",
      "newStatus": "APPROVED",
      "occurredAt": "2026-08-27T19:18:39Z",
      "previousStatus": "AWAITING_CONCLUSION"
    }
  ],
  "next_cursor": null,
  "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-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-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 the state transitions of an authorization

Returns the append-only audit of one mandate: previous state, new state, instant, actor, correlation, and the operation identifier when the transition came from an external invocation. The projection is never updated and never deleted from.

Ordering is by the instant the transition HAPPENED (occurredAt), which is also what the cursor resumes on — not the write instant.

A mandate belonging to another payer account is answered 404, exactly as one that does not exist: the account in X-Account-Id is a predicate on the lookup, so this end never learns the mandate exists elsewhere and cannot confirm it.

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

GET

payer

authorizations

{authorization_id}

history

List the state transitions of an authorization

curl --request GET \
  --url https://api.example.com/pixauto/v1/payer/authorizations/{authorization_id}/history \
  --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/authorizations/{authorization_id}/history"

	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/authorizations/{authorization_id}/history', 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/authorizations/{authorization_id}/history"

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

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

print(response.text)

{
  "items": [
    {
      "actor": "PAYER",
      "id": "01a044a8-f3bd-7d16-b8d9-6a5cf0319996",
      "newStatus": "AWAITING_CONCLUSION",
      "occurredAt": "2026-08-27T19:18:38Z"
    },
    {
      "actor": "RECEIVER_PSP",
      "id": "01a044a8-f4d6-76a1-aa32-a732ac2e8023",
      "newStatus": "APPROVED",
      "occurredAt": "2026-08-27T19:18:39Z",
      "previousStatus": "AWAITING_CONCLUSION"
    }
  ],
  "next_cursor": null,
  "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-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-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}$

Path Parameters

authorization_id

string

required

Internal identifier of the mandate whose transitions are being read. A request or mandate that exists under a DIFFERENT account than X-Account-Id names is answered 404, not 403: the lookup carries the account as a predicate, so this end never learns that a resource exists elsewhere and cannot confirm it.

Example:

"01a044a8-f3bd-7488-a0dc-e8d4be4802be"

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 history entries.

items

object[]

required

Empty array when there are no results — never null.

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 the state transitions of an authorization

Authorizations

Headers

Path Parameters

Query Parameters

Response