/pix/key/list List Pix Keys

Background

/pix/key/list queries Pix Keys, account names, and identity document numbers. The endpoint is shared by merchants and partners.

The data of this endpoint is an array directly, not an object containing an items field; when the account has no Pix Key, an empty array [] is returned.

Endpoint

Item	Value
Method	GET
Path	/pix/key/list
Content-Type	application/json
Purpose	Query the list of registered Pix Keys

Access Requirements

• Common Authentication

Request Fields

Field	Location	Type	Max Length	Required	Description
X-Merchant-Id	Header	string	64	Yes	Merchant ID of the integrator; partners use the primary merchant ID.
X-Timestamp	Header	int	19	Yes	Unix request timestamp in seconds, used to validate request freshness.
X-Nonce	Header	string	64	Yes	Anti-replay random string for the request.
Digest	Header	string	52	Yes	For a GET request without a body, compute the digest over an empty byte string, in the format SHA-256=<Base64 digest>.
Authorization	Header	string	Variable	Yes	ES256 request signature information, where keyId is the integrator's key version number.

This endpoint has no query parameters and no request body. For partners, each Pix Key record in the response additionally returns the sub-merchant ID subMerchantNo that the Pix Key belongs to.

Request Example

GET /pix/key/list HTTP/1.1
Content-Type: application/json
X-Merchant-Id: 92315566000120
X-Timestamp: 1786867200
X-Nonce: 550e8400-e29b-41d4-a716-446655440002
Digest: SHA-256=<Base64 digest>
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"

Response Fields

The endpoint uses the standard status, msg, and data response structure, where data is an array of Pix Keys.

Field	Type	Max Length	Always Returned	Description
status	int	4	Yes	Response code
msg	string	128	Yes	Corresponds to status
data	array	N/A	No	List of Pix Keys; [] when the request succeeds and there is no data, and it may be omitted when signature verification or protocol parsing fails.
data[].subMerchantNo	string	64	Yes	The sub-merchant ID that this Pix Key belongs to.
data[].key	string	64	Yes	The Pix Key or receiving identifier.
data[].ownerName	string	256	Yes	Account holder's name or business name, with the same meaning as data.ownerName in the Query Pix Key Info endpoint.
data[].taxNo	string	64	Yes	Tax ID of the account corresponding to the Pix Key: CPF for personal accounts, CNPJ for business accounts.

Response Example

{
  "status": 200,
  "msg": "sucesso",
  "data": [
    {
      "subMerchantNo": "SUB00000001",
      "key": "financeiro@example.com",
      "ownerName": "Example Financeiro Ltda.",
      "taxNo": "12345678000195"
    },
    {
      "subMerchantNo": "SUB00000001",
      "key": "+5511999990000",
      "ownerName": "Example Financeiro Ltda.",
      "taxNo": "12345678000195"
    }
  ]
}

Response Error Codes

• Response Status