/pix/key/list Pix Key 列表查询接口

接口背景

/pix/key/list 查询 Pix Key、账户名称及证件号。商户和合作商共用本接口。

本接口的 data 直接为数组，不是包含 items 字段的对象；账户没有 Pix Key 时返回空数组 []。

接口请求地址

项目	内容
请求方式	GET
请求路径	/pix/key/list
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 为接入方密钥版本号。

本接口无 Query 参数和请求体。合作商响应中每条 Pix Key 记录额外返回所属的二级商户号 subMerchantNo。

请求示例

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

接口响应字段

接口使用统一的 status、msg、data 响应结构，其中 data 为 Pix Key 数组。

字段名	类型	字段长度	是否必返	说明
status	int	4	是	响应码
msg	string	128	是	与 status 对应
data	array	不适用	否	Pix Key 列表；成功且无数据时为 []，验签或协议解析失败时可能不返回。
data[].subMerchantNo	string	64	是	该 Pix Key 所属的二级商户号。
data[].key	string	64	是	Pix Key 或收款标识。
data[].ownerName	string	256	是	账户持有人姓名或企业名称，与详情接口的 data.ownerName 含义一致。
data[].taxNo	string	64	是	Pix Key 对应账户的税号，个人账户为 CPF，企业账户为 CNPJ。

响应示例

{
  "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"
    }
  ]
}

响应错误码

• 响应状态