/pix/key/info Query Pix Key Info

Background

/pix/key/info queries the Pix Key type, holder, and tax ID by the payee's Pix Key. The endpoint is shared by merchants and partners.

This endpoint returns sensitive information such as names, tax IDs, and Pix Keys. Callers should use it only for transaction confirmation scenarios and avoid recording it in plaintext in logs.

Endpoint

Item	Value
Method	GET
Path	/pix/key/info
Content-Type	application/json
Purpose	Query the payee that corresponds to a Pix Key

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, used for gateway access authentication and key lookup; 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.
key	Query	string	64	Yes	The payee Pix Key to query; email, mobile number, CPF, CNPJ, or EVP are supported.

This endpoint has no request body. key is placed in the query string, and (request-target) in the canonical string includes the raw query string exactly as sent.

Request Example

GET /pix/key/info?key=financeiro%40example.com HTTP/1.1
Content-Type: application/json
X-Merchant-Id: 92315566000120
X-Timestamp: 1786867200
X-Nonce: 550e8400-e29b-41d4-a716-446655440003
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.

Field	Type	Max Length	Always Returned	Description
status	int	4	Yes	Response code
msg	string	128	Yes	Corresponds to status
data	object	N/A	No	Pix Key details; it may be omitted when the request fails at the signature verification or protocol parsing stage.
data.subMerchantNo	string	64	Yes	Sub-merchant ID, additionally returned when the query is made by a partner.
data.key	string	64	Yes	The Pix Key or receiving identifier.
data.keyType	string	10	Yes	Pix Key type: PHONE for mobile number, EMAIL for email, CPF for the Brazilian personal tax ID, CNPJ for the Brazilian business tax ID, and EVP for a system-generated random key.
data.ownerName	string	256	Yes	Account holder's name or business name.
data.personType	string	64	Yes	Holder type, for example natural person or legal person.
data.taxNo	string	64	Yes	Tax ID of the account holder: CPF for personal accounts, CNPJ for business accounts.

Response Example

{
  "status": 200,
  "msg": "sucesso",
  "data": {
    "subMerchantNo": "SUB00000001",
    "key": "financeiro@example.com",
    "keyType": "EMAIL",
    "ownerName": "Example Financeiro Ltda.",
    "personType": "LEGAL_PERSON",
    "taxNo": "12345678000195"
  }
}

Response Error Codes

• Response Status