Gerenciando chaves Pix

A API de Contas (/api/v2) permite listar, criar e remover as chaves Pix da conta autenticada.

Operação	Método e path	Scope
Listar chaves da conta	`GET /accounts/keys`	`pix.read`
Solicitar OTP (EMAIL/PHONE)	`POST /accounts/keys/challenge`	`pix.write`
Criar chave	`POST /accounts/keys`	`pix.write`
Remover chave	`DELETE /accounts/keys/{key}`	`pix.write`

Importante: GET /pix/keys/{key} consulta o DICT de qualquer chave informada. Não lista nem gerencia as chaves da sua conta. Para isso, use /accounts/keys.

Todas as requisições abaixo usam:

Authorization: Bearer <access_token>
x-account-id: <id da conta> (quando a credencial for BaaS)

Base URL: https://secureapi.onz.finance/api/v2

Quais tipos de chave posso criar?

Tipo	OTP necessário?	Observação
`EVP`	Não	Chave aleatória gerada pelo DICT. Não envie `key`.
`CPF`	Não	Deve ser igual ao CPF da conta (pessoa física).
`CNPJ`	Não	Deve ser igual ao CNPJ da conta (pessoa jurídica).
`EMAIL`	Sim	Exige fluxo de challenge + código OTP.
`PHONE`	Sim	Exige fluxo de challenge + código OTP. Telefone no formato E.164 (ex.: `+5511999999999`).

Fluxo com OTP (EMAIL e PHONE)

Para criar chave de e-mail ou telefone, a posse do contato precisa ser comprovada com um código OTP.

1. POST /accounts/keys/challenge
   → envia o OTP para o e-mail/telefone
   → devolve validationHash (auth hash)

2. Usuário informa o código recebido (validationCode)

3. POST /accounts/keys
   → envia keyType, key, validationHash e validationCode
   → cria a chave no DICT

Passo 1 — Solicitar o OTP (`challenge`)

curl --location 'https://secureapi.onz.finance/api/v2/accounts/keys/challenge' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --header 'x-account-id: <account_id>' \
  --data '{
    "keyType": "EMAIL",
    "key": "usuario@exemplo.com"
  }'

Resposta:

{
  "validationHash": "550e8400-e29b-41d4-a716-446655440000",
  "expiresIn": 300
}

Campo	Descrição
`validationHash`	Auth hash. Guarde e envie no `POST /accounts/keys`.
`expiresIn`	Validade do código OTP em segundos (300 = 5 minutos).

O código OTP é enviado para o e-mail ou telefone informado. Ele não vem na resposta da API.

Passo 2 — Criar a chave com hash + código

curl --location 'https://secureapi.onz.finance/api/v2/accounts/keys' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --header 'x-account-id: <account_id>' \
  --data '{
    "keyType": "EMAIL",
    "key": "usuario@exemplo.com",
    "validationHash": "550e8400-e29b-41d4-a716-446655440000",
    "validationCode": "1234"
  }'

Resposta (200):

{
  "key": "usuario@exemplo.com",
  "keyType": "EMAIL",
  "branch": "0001",
  "accountNumber": "123456",
  "accountType": "CACC",
  "name": "Cliente Exemplo",
  "taxIdNumber": "12345678901",
  "creationDate": "2024-01-01T12:00:00.000Z"
}

Regras do challenge

validationHash e validationCode são obrigatórios para EMAIL e PHONE.
O key do create deve ser o mesmo usado no challenge.
O código expira em 5 minutos.

Código de confirmação inválido, vencido ou já utilizado

Ao criar a chave em POST /accounts/keys, o retorno muda conforme o caso. Use o campo detail para escolher a mensagem na tela.

Situação	HTTP	type	detail	Mensagem sugerida
Código errado ou `validationHash` inexistente	404	`onz-0009`	Código inválido.	Código incorreto. Confira e tente novamente.
Código vencido	422	`onz-0026`	Código expirado.	Código vencido. Solicite um novo código.
Código já utilizado	422	`onz-0026`	Código já utilizado.	Esse código já foi usado. Solicite um novo código.

Exemplo de resposta:

{
  "detail": "Código expirado.",
  "title": "Failed to create Pix key",
  "type": "onz-0026"
}

Os erros de código vencido e de código já utilizado têm o mesmo type (onz-0026). Diferencie-os pelo detail.

Novo pedido de código

Cada chamada a POST /accounts/keys/challenge gera um novo validationHash. O pedido anterior não é invalidado e continua válido até vencer. Use sempre o validationHash mais recente e descarte os anteriores no seu app.

Chave já cadastrada

A criação de chave não abre portabilidade nem reivindicação automaticamente. A API repassa o erro do DICT:

Situação	HTTP	Erro do DICT	Próximo passo
Chave já cadastrada na própria conta, com o mesmo dono	400	`EntryAlreadyExists` (Chave já cadastrada)	Nada a fazer, a chave já existe.
Chave pertence a outra pessoa	400	`EntryKeyOwnedByDifferentPerson`	Caso de reivindicação de posse (fluxo separado).
Mesmo dono, mas a chave está em outra instituição	400	`EntryKeyInCustodyOfDifferentParticipant`	Caso de portabilidade (fluxo separado).

Criar chave sem OTP (EVP, CPF, CNPJ)

EVP (chave aleatória)

curl --location 'https://secureapi.onz.finance/api/v2/accounts/keys' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --header 'x-account-id: <account_id>' \
  --data '{
    "keyType": "EVP"
  }'

CPF / CNPJ

curl --location 'https://secureapi.onz.finance/api/v2/accounts/keys' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --header 'x-account-id: <account_id>' \
  --data '{
    "keyType": "CPF",
    "key": "12345678901"
  }'

O valor de key precisa ser exatamente o documento da conta.

Listar e remover

Listar

curl --location 'https://secureapi.onz.finance/api/v2/accounts/keys' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'x-account-id: <account_id>'

Remover

curl --location --request DELETE 'https://secureapi.onz.finance/api/v2/accounts/keys/usuario@exemplo.com' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'x-account-id: <account_id>'

DELETE /accounts/keys/{key} responde 202 depois de acionar a remoção no DICT. Não há fila local de remoção. Se a chamada passou, a listagem seguinte já tende a não trazer a chave, mas pode haver uma pequena latência entre DICT, CloudPix e listagem. Não há um prazo fixo garantido.

Depois que a remoção é efetivada no DICT, é possível cadastrar a mesma chave de novo. Pode impedir o novo cadastro:

tentativa imediata, antes de a remoção refletir;
chave travada por reivindicação;
cobrança QR ativa associada à chave, quando essa validação de remoção estiver habilitada;
a chave ter sido cadastrada por outra conta ou instituição nesse intervalo.

Se o cadastro falhar logo após a remoção, tente novamente depois de alguns segundos.

Referência OpenAPI

Consulte a referência da API de Contas (categoria Chaves Pix) para schemas e códigos de erro detalhados dos endpoints /accounts/keys, /accounts/keys/challenge, /accounts/keys/{key} e /pix/keys/{key}.

Quais tipos de chave posso criar?​

Fluxo com OTP (EMAIL e PHONE)​

Passo 1 — Solicitar o OTP (challenge)​

Passo 2 — Criar a chave com hash + código​

Regras do challenge​

Código de confirmação inválido, vencido ou já utilizado​

Novo pedido de código​

Chave já cadastrada​

Criar chave sem OTP (EVP, CPF, CNPJ)​

EVP (chave aleatória)​

CPF / CNPJ​

Listar e remover​

Listar​

Remover​

Referência OpenAPI​