/pix/key/modify Pix Key 修改接口
接口背景
/pix/key/modify 用于将新的银行账户绑定到请求上送的 Pix Key 上。商户和合作商共用本接口。待修改的 Pix Key 必须已经存在且处于激活状态。
仅 PHONE、EMAIL、CPF 和 CNPJ 类型的 Pix Key 支持修改绑定；EVP 类型的 Key 由系统生成，不支持修改。新绑定账户必须为已存在且激活的账户，且与该 Pix Key 当前归属账户属于同一接入方。修改仅变更 Pix Key 绑定的收款账户，Key 值本身不变，变更立即生效。
接口请求地址
| 项目 | 内容 |
|---|---|
| 请求方式 | POST |
| 请求路径 | /pix/key/modify |
| Content-Type | application/json |
| 接口用途 | 修改 Pix Key 绑定的银行账户 |
接口接入规范
接口请求字段
| 字段名 | 位置 | 类型 | 字段长度 | 是否必填 | 说明 |
|---|---|---|---|---|---|
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。 |
请求示例
http
POST /pix/key/modify HTTP/1.1
Content-Type: application/json
X-Merchant-Id: 92315566000120
X-Timestamp: 1786867200
X-Nonce: 550e8400-e29b-41d4-a716-446655440004
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"
}接口响应字段
接口使用统一的 status、msg、data 响应结构。
| 字段名 | 类型 | 字段长度 | 是否必返 | 说明 |
|---|---|---|---|---|
status | int | 4 | 是 | 响应码 |
msg | string | 128 | 是 | 与 status 对应 |
data | object | 不适用 | 否 | Pix Key 修改结果；请求在验签或协议解析阶段失败时可能不返回。 |
data.key | string | 64 | 是 | 修改成功后的 Pix Key，与请求上送的 Key 一致。 |
data.keyType | string | 10 | 是 | 已修改的 Pix Key 类型：PHONE 表示手机号，EMAIL 表示邮箱，CPF 表示巴西个人税号，CNPJ 表示巴西企业税号，EVP 表示系统生成的随机 Key。 |
响应示例
json
{
"status": 200,
"msg": "sucesso",
"data": {
"key": "financeiro@example.com",
"keyType": "EMAIL"
}
}