/pix/key/info Pix Key 详情查询接口

接口背景

/pix/key/info 用于根据收款方 Pix Key 查询 Pix Key 类型、持有人及税号信息。商户和合作商共用本接口。

本接口返回姓名、税号和 Pix Key 等敏感信息，调用方应仅在交易确认场景中使用，并避免在日志中明文记录。

接口请求地址

项目	内容
请求方式	GET
请求路径	/pix/key/info
Content-Type	application/json
接口用途	查询 Pix Key 对应的收款方

接口接入规范

• common接入规范

接口请求字段

字段名	位置	类型	字段长度	是否必填	说明
X-Merchant-Id	Header	string	64	是	接入方商户号，用于网关接入认证和密钥定位；合作商使用一级商户号。
X-Timestamp	Header	int	19	是	Unix 秒级请求时间戳，用于请求时效校验。
X-Nonce	Header	string	64	是	请求防重放随机字符串。
Digest	Header	string	52	是	GET 请求无报文体时使用空字节串计算摘要，格式为 SHA-256=<Base64摘要>。
Authorization	Header	string	不定长	是	ES256 请求签名信息，其中 keyId 为接入方密钥版本号。
key	Query	string	64	是	待查询的收款方 Pix Key，支持邮箱、手机号、CPF、CNPJ 或 EVP。

本接口无请求体。key 放在 Query 中，签名串中的 (request-target) 包含实际发送的原始 Query 字符串。

请求示例

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摘要>
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"

接口响应字段

接口使用 status、msg、data 响应结构。

字段名	类型	字段长度	是否必返	说明
status	int	4	是	响应码
msg	string	128	是	与 status 对应
data	object	不适用	否	Pix Key 详情；请求在验签或协议解析阶段失败时可能不返回。
data.subMerchantNo	string	64	是	二级商户号，合作商查询时额外返回。
data.key	string	64	是	Pix Key 或收款标识。
data.keyType	string	10	是	Pix Key 类型：PHONE 表示手机号，EMAIL 表示邮箱，CPF 表示巴西个人税号，CNPJ 表示巴西企业税号，EVP 表示系统生成的随机 Key。
data.ownerName	string	256	是	账户持有人姓名或企业名称。
data.personType	string	64	是	持有人类型，例如自然人或法人。
data.taxNo	string	64	是	账户持有人的税号，个人账户为 CPF，企业账户为 CNPJ。

响应示例

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

响应错误码

• 响应状态