/pix/key/modify Modify Pix Key
Background
/pix/key/modify binds a new bank account to the Pix Key submitted in the request. The endpoint is shared by merchants and partners. The Pix Key to modify must already exist and be in the activated state.
Only Pix Keys of the PHONE, EMAIL, CPF, and CNPJ types support rebinding; an EVP key is generated by the system and does not support modification. The new account must already exist and be activated, and it must belong to the same integrator as the account that the Pix Key currently belongs to. The modification only changes the receiving account bound to the Pix Key; the key value itself is unchanged, and the change takes effect immediately.
Endpoint
| Item | Value |
|---|---|
| Method | POST |
| Path | /pix/key/modify |
| Content-Type | application/json |
| Purpose | Modify the bank account bound to a Pix Key |
Access Requirements
Request Fields
| Field | Location | Type | Max Length | Required | Description |
|---|---|---|---|---|---|
X-Merchant-Id | Header | string | 64 | Yes | Merchant ID of the integrator; 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 | Digest of the request body, 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 | Body | string | 64 | Yes | A Pix Key that already exists and is in the activated state. |
Request Example
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 digest>
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"
{
"key": "financeiro@example.com"
}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 modification result; it may be omitted when the request fails at the signature verification or protocol parsing stage. |
data.key | string | 64 | Yes | The Pix Key after the successful modification, identical to the key submitted in the request. |
data.keyType | string | 10 | Yes | The modified 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. |
Response Example
json
{
"status": 200,
"msg": "sucesso",
"data": {
"key": "financeiro@example.com",
"keyType": "EMAIL"
}
}