/pix/key/register Pix Key 注册接口

接口背景

/pix/key/register 用于将指定类型的 Pix Key 绑定到商户银行账户。商户和合作商共用本接口。

Pix Key 类型支持 PHONE、EMAIL、CPF、CNPJ 和 EVP。PHONE、EMAIL 类型需传入 key；CPF、CNPJ 类型无需上送 key，由系统按商户登记的税号注册；EVP 类型的 Key 由系统生成，请求时不传 key。注册手机号或邮箱类型前，需先调用验证码发送接口，并将验证码填写到 token、将响应中的 data.verificationRequestId 填写到 verificationRequestId。

接口请求地址

项目	内容
请求方式	POST
请求路径	/pix/key/register
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	是	请求体摘要，格式为 SHA-256=<Base64摘要>。
Authorization	Header	string	不定长	是	ES256 请求签名信息，其中 keyId 为接入方密钥版本号。
key	Body	string	64	条件必填	Pix Key 值。PHONE、EMAIL 类型必填；CPF、CNPJ 类型无需上送，由系统按商户登记的税号注册；EVP 类型不填。手机号建议使用带国家码的国际格式，例如巴西手机号 +5511999999999。
keyType	Body	string	10	是	Pix Key 类型：PHONE 表示手机号，EMAIL 表示邮箱，CPF 表示巴西个人税号，CNPJ 表示巴西企业税号，EVP 表示系统生成的随机 Key。
token	Body	string	6	条件必填	手机号或邮箱 Pix Key 收到的 6 位验证码；PHONE、EMAIL 类型必填，其他类型不填。
verificationRequestId	Body	string	64	条件必填	验证请求 ID，长度为 64 个字符，取自验证码发送接口响应中的 data.verificationRequestId；PHONE、EMAIL 类型必填，其他类型不填。

请求示例

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

{
  "key": "financeiro@example.com",
  "keyType": "EMAIL",
  "token": "123456",
  "verificationRequestId": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}

接口响应字段

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

字段名	类型	字段长度	是否必返	说明
status	int	4	是	响应码
msg	string	128	是	与 status 对应
data	object	不适用	否	Pix Key 注册结果；请求在验签或协议解析阶段失败时可能不返回。
data.key	string	64	是	注册成功后的 Pix Key；EVP 类型返回系统生成的随机 Key。
data.keyType	string	10	是	已注册的 Pix Key 类型：PHONE 表示手机号，EMAIL 表示邮箱，CPF 表示巴西个人税号，CNPJ 表示巴西企业税号，EVP 表示系统生成的随机 Key。

响应示例

{
  "status": 200,
  "msg": "sucesso",
  "data": {
    "key": "financeiro@example.com",
    "keyType": "EMAIL"
  }
}

响应错误码

• 响应状态