Criação de pedido de reivindicação

O endpoint de reivindicação de chaves Pix possibilita solicitar a portabilidade ou a posse de uma chave Pix, de acordo com a necessidade de seu cliente.

📘
Nota
Após a criação de um pedido de reivindicação de posse de chave Pix, é necessário completar o pedido.

Pré-requisito

Para que seja possível utilizar este endpoint, é necessário que:

O cliente possua uma conta ativa.

Requisição (Request)

Requisição HTTP

POST https://sandbox.hiperbanco.com.br/pix/pix-key-claims

--request POST 'https://sandbox.hiperbanco.com.br/pix/pix-key-claims' \
--header 'version: cutting-edge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
--data-raw '{
  "type": "PORTABILITY",
  "addressingKey": {
    "type": "CPF",
    "value": "15654785236"
  }
}'

Cabeçalhos (Headers)

Nome	Propriedade	Descrição
version	cutting-edge	Essa propriedade garante que o response da API seja retornado no formato JSON
Authorization	Bearer token	Obrigatório. Token de autorização do tipo Bearer.

Parâmetros da rota (Path)

Não é necessário enviar parâmetros no path desta requisição.

Corpo da requisição (Body)

No body, envie os seguintes campos em formato JSON:

Nome	Tipo	Descrição	Especificação
type	string	Obrigatório. Tipo de reivindicação, que pode ser "PORTABILITY" (portabilidade) ou "OWNERSHIP" (posse).	—
addressingKey	object	Obrigatório. Objeto que deverá conter informações sobre a chave de endereçamento.	—
addressingKey.type	string	Obrigatório. Tipo de chave, que pode ser "CPF", "CNPJ", "PHONE" ou "EMAIL".	—
addressingKey.value	string	Obrigatório. Valor da chave.	—

{
  "type": "PORTABILITY",
  "addressingKey": {
    "type": "CPF",
    "value": "47742663023"
  }
}

{
  "type": "OWNERSHIP",
  "addressingKey": {
    "type": "PHONE",
    "value": "+5511911111111"
  }
}

Resposta (Response)

O status code 201 indicará sucesso na criação do pedido de reinvindicação.Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:

{
  "data": {
    "pixKeyClaim": {
      "id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
      "type": "PORTABILITY",
      "status": "OPEN",
      "addressingKey": {
        "type": "CPF",
        "value": "12345678901"
      },
      "claimer": {
        "branch": "0001",
        "number": "98765",
        "bank": {
          "name": "Acesso Soluções de Pagamento S.A",
          "ispb": "13140088"
        }
      },
      "donorActionLimitDate": "2025-08-27T02:46:32.030Z",
      "createdAt": "2025-08-12T20:46:32.427Z",
      "updatedAt": "2025-08-12T20:46:32.427Z"
    }
  }
}

{
  "data": {
    "pixKeyClaim": {
      "id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
      "type": "OWNERSHIP",
      "status": "OPEN",
      "addressingKey": {
        "type": "PHONE",
        "value": "+5599999999999"
      },
      "claimer": {
        "branch": "0001",
        "number": "98765",
        "bank": {
          "name": "Acesso Soluções de Pagamento S.A",
          "ispb": "13140088"
        }
      },
      "donorActionLimitDate": "2025-08-27T02:46:32.030Z",
      "createdAt": "2025-08-12T20:46:32.427Z",
      "updatedAt": "2025-08-12T20:46:32.427Z"
    }
  }
}

Possíveis status

Status	Descrição
OPEN	Solicitação aberta pelo reivindicador, mas ainda não recebida pelo doador.
WAITING_RESOLUTION	A reivindicação já foi recebida pelo doador e está aguardando a resolução.
CONFIRMED	O doador confirmou o pedido de reivindicação e vai ceder a chave para a outra instituição. Isso implica a remoção da chave do DICT e da base interna do PSP doador. Está aguardando o reivindicador encerrar o processo.
WATING_VALIDATION	Após a confirmação, indica-se que o ConclusionLimitDate foi atingido. A partir deste momento, a reivindicação passa a ter o status de WAITING_VALIDATION, permitindo ao reivindicador realizar a validação de posse (TOTP) e concluir a reivindicação. Isso é aplicável apenas para reivindicações de posse (OWNERSHIP).
CANCELED	O doador ou reivindicador cancelou a reivindicação, mantendo o vínculo inalterado (conforme estava antes da reivindicação), tanto no DICT quanto na base interna do PSP.
COMPLETED	O pedido de portabilidade ou posse foi completado com sucesso e a chave foi transferida para o Hiperbanco.

Erros

Este endpoint pode retornar erros específicos, conforme a tabela a seguir:

Status code	Código	Mensagem	Descrição
404	CLAIM_NOT_FOUND	Claim not found.	Pedido de reivindicação não encontrado.
422	CANNOT_REGISTER_CLAIM_TO_EVP_TYPE	Cannot register portability claim and ownership claim to EVP type.	Não é possível reivindicar a portabilidade e a posse de uma chave do tipo EVP.
422	CANNOT_REGISTER_OWNERSHIP_CLAIM_TO_CPF_TYPE	Cannot register ownership claim to CPF type.	Não é possível reivindicar a posse de uma chave do tipo CPF.
422	CANNOT_REGISTER_OWNERSHIP_CLAIM_TO_CNPJ_TYPE	Cannot register ownership claim to CNPJ type.	Não é possível reivindicar a posse de uma chave do tipo CNPJ.
422	CLAIM_CAN_ONLY_BE_REGISTERED_BY_CLAIMER_ACCOUNT_HOLDER	Portability claim and ownership claim only can be registered by claimer account holder.	A reivindicação de portabilidade e de posse somente pode ser feita pelo titular da conta.
422	INVALID_CLAIM_TYPE_USED_ON_REQUEST	Requested claim type is inconsistent.	O tipo de reivindicação informado é incorreto. Esse erro ocorre quando: A) uma posse é solicitada por quem já possui a chave (o correto seria portabilidade), ou B) a portabilidade é solicitada por quem não é o atual possuidor (o correto seria posse).
422	CLAIM_RESULTING_ENTRY_ALREADY_EXISTS	Bond that would result when processing the claim already exists, with the same key, participant and owner.	O vínculo com a chave reivindicada já existe.
422	CLAIM_ALREADY_EXISTS_FOR_ENTRY	Claim already exists for the addressing key.	A reivindicação já existe para essa chave de endereçamento.
422	INVALID_CLAIM	Exist invalid fields when trying to create the claim.	Há campos com preenchimento incorreto.
422	PIX_KEY_NOT_FOUND	The Pix key provided was not found or does not exist.	A chave Pix fornecida não foi encontrada ou não existe.
422	INVALID_KEY_FORMAT	Invalid key format	Formato de chave inválido

Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints que acompanham os erros 400 (se houver).

Eventos

Caso o parceiro deseje receber mensagens referentes aos eventos relacionados a esse endpoint, é preciso configurar o webhook. Os eventos são:

Nome do evento	Descrição
PIX_CLAIM_WAS_REGISTERED	Um cliente do parceiro Hiperbanco registrou um pedido de reivindicação de posse/portabilidade para outra instituição.