Update PIX key

Updates a PIX key’s mutable bindings (account branch/number/type and owner name/trade name) and reports the change to BACEN DICT (signed updateEntry). keyType and ownerTaxId are immutable; an attempt to change them is rejected. The body carries no participant: for a held key the wire Participant is its stored owning participant, so this verb can never rebind a key to another participant. A key this service does not hold (for example one rebuilt by the participant’s VSync) is updated at BACEN on the binding the caller states — X-ISPB, keyType and ownerTaxId, plus accountNumber, accountType and openingDate when the account moves — and nothing local is written. A BACEN refusal such as EntryBlocked (judicial block) is relayed with its own token and HTTP status.

PUT /api/v1/dict/keys/{key}

Update PIX key

cURL

curl --request PUT \
  --url https://api.example.com/api/v1/dict/keys/{key} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "reason": "BRANCH_TRANSFER",
  "accountNumber": "9988776",
  "accountType": "CACC",
  "branch": "0001",
  "keyType": "CPF",
  "openingDate": "2020-01-15T00:00:00Z",
  "ownerName": "João Silva",
  "ownerTaxId": "12345678901",
  "ownerTradeName": "Silva ME"
}
'

200

{
  "createdAt": "2025-03-07T14:30:00Z",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "keyType": "CPF",
  "keyValue": "12345678901",
  "ownerName": "João Silva",
  "ownerTaxId": "12345678901",
  "participantISPB": "12345678",
  "status": "ACTIVE",
  "updatedAt": "2025-03-07T14:30:00Z",
  "accountNumber": "9988776",
  "accountType": "CACC",
  "bacen": {
    "correlationId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "lastModified": "2026-06-14T12:00:00Z",
    "responseTime": "2026-06-14T12:00:00Z"
  },
  "branch": "0001",
  "creationDate": "2020-01-15T00:00:00Z",
  "keyOwnershipDate": "2020-01-15T00:00:00Z",
  "openingDate": "2020-01-15T00:00:00Z",
  "ownerTradeName": "Silva ME",
  "ownerType": "NATURAL_PERSON",
  "requestId": "b2696bf1-0a51-48b0-ab4a-8af2dff440af"
}

Autorizações

Authorization · string · header · obrigatório

JWT bearer token issued by the identity provider.

Cabeçalhos

X-Idempotency · string · obrigatório

Idempotency key, max 255 characters

X-ISPB · string

ISPB of the participant the key is bound to, authorized like any other participant this deployment acts for. Required for a key this service does not hold (for example one rebuilt by the participant's VSync); for a held key it may only restate the stored participant.

Pattern: ^[0-9A-Z]{8}$

Exemplo:

"12345678"

Parâmetros de caminho

key · string · obrigatório

PIX key value to update (the immutable identifier).

Corpo

application/json

Mutable key fields (account + owner name/trade name) and the update reason; keyType and ownerTaxId are immutable and rejected if changed.

reason · enum<string> · obrigatório

Update reason: USER_REQUESTED (not for EVP keys), BRANCH_TRANSFER, RECONCILIATION, or RFB_VALIDATION. This is the subset BACEN's updateEntry accepts; the wider EntryOperationReason set is not valid on an update.

Opções disponíveis: USER_REQUESTED, BRANCH_TRANSFER, RECONCILIATION, RFB_VALIDATION

Exemplo:

"BRANCH_TRANSFER"

accountNumber · string

New account number (account mutable field).

Exemplo:

"9988776"

accountType · string

New account type (account mutable field).

Exemplo:

"CACC"

branch · string

New account branch (account mutable field).

Exemplo:

"0001"

keyType · string

Immutable: supplying a value differing from the stored keyType is rejected.

Exemplo:

"CPF"

openingDate · string<date-time>

Account opening date, RFC 3339. Used only for a key this service does not hold, where it is required with accountNumber and accountType when the account moves; a held key always sends its stored opening date.

Exemplo:

"2020-01-15T00:00:00Z"

ownerName · string

New owner legal name (owner mutable field).

Exemplo:

"João Silva"

ownerTaxId · string

Immutable: supplying a value differing from the stored ownerTaxId is rejected.

Exemplo:

"12345678901"

ownerTradeName · string

New owner trade name (owner mutable field).

Exemplo:

"Silva ME"

Resposta

200

application/json

OK

Updated PIX key with its mutable fields applied

createdAt · string · obrigatório

Key creation timestamp, RFC 3339 (UTC) — OUR row's local timestamp, not BACEN's; see creationDate for the DICT's own binding-creation instant.

Exemplo:

"2025-03-07T14:30:00Z"

id · string · obrigatório

Unique PIX key identifier (UUID) assigned by the service.

Exemplo:

"550e8400-e29b-41d4-a716-446655440000"

keyType · string · obrigatório

PIX key type: CPF, CNPJ, EMAIL, PHONE, or EVP (random key).

Exemplo:

"CPF"

keyValue · string · obrigatório

PIX key value in its canonical format for the key type.

Exemplo:

"12345678901"

ownerName · string · obrigatório

Full legal name of the key owner.

Exemplo:

"João Silva"

ownerTaxId · string · obrigatório

Owner tax identifier: 11 digits for a CPF, 14 alphanumeric characters for a CNPJ (IN RFB 2.229/2024).

Exemplo:

"12345678901"

participantISPB · string · obrigatório

Owning participant ISPB, the BACEN institution identifier (8 digits or uppercase letters).

Exemplo:

"12345678"

status · string · obrigatório

Key lifecycle status: ACTIVE or PENDING_CLAIM.

Exemplo:

"ACTIVE"

updatedAt · string · obrigatório

Timestamp of the last update to the key, RFC 3339 (UTC).

Exemplo:

"2025-03-07T14:30:00Z"

accountNumber · string

Account number (1..20 digits), omitted for a tuple-less key.

Exemplo:

"9988776"

accountType · enum<string>

BACEN account type (CACC, SVGS, TRAN, SLRY, OTHR), omitted for a tuple-less key.

Opções disponíveis: CACC, SVGS, TRAN, SLRY, OTHR

Exemplo:

"CACC"

bacen · object

BACEN's own operational envelope for its most recent interaction on this key; omitted when no BACEN interaction has ever landed on it.

Show child attributes

branch · string

Account branch (1..4 digits), omitted when unset.

Exemplo:

"0001"

creationDate · string<date-time>

BACEN's own creation instant for this key/account/owner binding, as the DICT answered it; omitted when BACEN's answer carried none.

Exemplo:

"2020-01-15T00:00:00Z"

keyOwnershipDate · string<date-time>

Instant from which the owner has held uninterrupted possession of this key per BACEN; may differ from creationDate after a portability. Omitted when BACEN's answer carried none.

Exemplo:

"2020-01-15T00:00:00Z"

openingDate · string<date-time>

Account opening date, RFC 3339, omitted for a tuple-less key.

Exemplo:

"2020-01-15T00:00:00Z"

ownerTradeName · string

Owner trade name (legal-entity owners), omitted when unset.

Exemplo:

"Silva ME"

ownerType · enum<string>

BACEN's own Person discriminator for the owner, as the DICT published it — not the value the registration declared, which is refused when the two could disagree. Omitted when BACEN's answer carried none.

Opções disponíveis: NATURAL_PERSON, LEGAL_PERSON

Exemplo:

"NATURAL_PERSON"

requestId · string<uuid>

The participant's own identifier for the registration that created this binding, echoed back. It is the value BACEN holds against the vinculo for life, so it is what a DICT support case and a retry are addressed by. Omitted for a key registered before this field existed, which had no caller to state one.

Exemplo:

"b2696bf1-0a51-48b0-ab4a-8af2dff440af"