Consulta dos pedidos de reivindicação

O endpoint de consulta de pedidos de reivindicação permite:

Acompanhar as solicitações de reivindicação de posse ou portabilidade de chaves realizadas pelos clientes dos parceiros Hiperbanco;
Verificar se há pedidos de reivindicação provenientes de outras instituições financeiras direcionados aos clientes dos parceiros Hiperbanco.

Requisição (Request)

Requisição HTTP

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

--request GET 'https://sandbox.hiperbanco.com.br/pix/pix-key-claims' \
--header 'version: cutting-edge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}'

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)

Não é necessário enviar campos no body desta requisição.

Resposta (Response)

O status code 200 indicará sucesso na consulta.Sendo bem-sucedido, o retorno irá trazer uma lista com os seguintes campos em formato JSON:

Nome	Tipo	Descrição
data	object	Objeto principal da resposta.
data.pixKeyClaims	array	Lista de reivindicações de chaves Pix.
data.pixKeyClaims[].id	string	Identificação única de pedido de portabilidade ou posse. Esse valor deverá ser utilizado todas as vezes que você realizar uma operação referente a essa reivindicação, como consulta, cancelamento etc.
data.pixKeyClaims[].type	string	Tipo de reivindicação, que pode ser "PORTABILITY" (portabilidade) ou "OWNERSHIP" (posse).
data.pixKeyClaims[].status	string	Situação do pedido de reivindicação.
data.pixKeyClaims[].addressingKey	object	Objeto que contém informações sobre a chave de endereçamento.
data.pixKeyClaims[].addressingKey.type	string	Tipo de chave, que pode ser "CPF", "CNPJ", "PHONE" ou "EMAIL".
data.pixKeyClaims[].addressingKey.value	string	Valor da chave.
data.pixKeyClaims[].claimer	object	Objeto que contém informações sobre o banco a conta do reivindicador.
data.pixKeyClaims[].claimer.branch	string	Número da agência.
data.pixKeyClaims[].claimer.number	string	Número da conta.
data.pixKeyClaims[].claimer.bank	object	Objeto que contém informações sobre o banco do reivindicador.
data.pixKeyClaims[].claimer.bank.name	string	Nome da instituição financeira do requerente.
data.pixKeyClaims[].claimer.bank.ispb	string	ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco do reivindicador.
data.pixKeyClaims[].donor	object	Objeto que contém informações sobre a conta do doador.
data.pixKeyClaims[].donor.branch	string	Número da agência.
data.pixKeyClaims[].donor.number	string	Número da conta.
data.pixKeyClaims[].donor.bank	object	Objeto que contém informações sobre o banco do doador.
data.pixKeyClaims[].donor.bank.name	string	Nome do banco do doador.
data.pixKeyClaims[].donor.bank.ispb	string	ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco do doador.
data.pixKeyClaims[].donorActionLimitDate	string	Data limite para o doador de posse e o reivindicador (tanto de posse como de portabilidade) confirmarem ou cancelarem o pedido, no formato ISO 8601 - UTC. Data limite para o doador realizar ações, como concluir ou cancelar o pedido de reivindicação, no formato ISO 8601 - UTC.
data.pixKeyClaims[].createdAt	string	Data de criação do pedido de reivindicação, no formato ISO 8601 - UTC.
data.pixKeyClaims[].updatedAt	string	Data de atualização do pedido de reivindicação, no formato ISO 8601 - UTC.
data.pixKeyClaims[].confirmReason	string	Motivo da confirmação do pedido de reinvindicação, que pode ser "DONOR_REQUEST", retornado quando o dono da chave realiza a doação para o reivindicador; "DEFAULT_OPERATION", quando o sistema confirma a doação de uma chave que já completou 15 dias em WAITING_RESOLUTION (somente em caso de posse); ou "ACCOUNT_CLOSURE" (encerramento de conta).
data.pixKeyClaims[].cancelReason	string	Motivo do cancelamento do pedido de reinvindicação.

📘
Nota
Os campos retornados poderão variar, de acordo com a situação (status) em que o pedido de reivindicação se encontra.

O Retorno 1 traz detalhes dos pedidos de reivindicação de chaves abertos por um cliente do parceiro Hiperbanco (caso em que o cliente é o reivindicador).

Já o Retorno 2 refere-se a um pedido de reivindicação proveniente de outra instituição financeira para um cliente do parceiro Hiperbanco (nesse caso, o cliente é o doador).

{
  "data": {
    "pixKeyClaims": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "OWNERSHIP",
        "status": "OPEN",
        "addressingKey": {
          "type": "PHONE",
          "value": "+5521998765432"
        },
        "claimer": {
          "branch": "1234",
          "number": "9876543210",
          "bank": {
            "name": "Acesso Soluções de Pagamento S.A",
            "ispb": "13140088"
          }
        },
        "donorActionLimitDate": "2025-08-04T17:00:00.000Z",
        "createdAt": "2025-07-20T14:00:00.000Z",
        "updatedAt": "2025-07-21T10:30:00.000Z"
      }
    ]
  }
}

{
  "data": {
    "pixKeyClaims": [
      {
        "id": "f9a1b2c3-4d5e-6789-90ab-cdef12345678",
        "type": "OWNERSHIP",
        "status": "WAITING_RESOLUTION",
        "addressingKey": {
          "type": "PHONE",
          "value": "+5521987654321"
        },
        "claimer": {
          "branch": "1234",
          "number": "9876543210",
          "bank": {
            "name": "Banco Digital Fictício S.A.",
            "ispb": "18236120"
          }
        },
        "donor": {
          "branch": "5678",
          "number": "1234567890",
          "bank": {
            "name": "Banco Virtual do Brasil S.A.",
            "ispb": "11112222"
          }
        },
        "donorActionLimitDate": "2025-08-04T17:01:27.000Z",
        "createdAt": "2025-07-21T14:01:28.657Z",
        "updatedAt": "2025-07-21T14:01:48.927Z"
      }
    ]
  }
}

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.
WAITING_VALIDATION	Após a confirmação, indica-se que o donorActionLimitDate 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.

Motivo do cancelamento do pedido de reinvindicação

Motivo	Descrição
CLAIMER_REQUEST	Cancelado pelo reivindicador.
DONOR_REQUEST	Cancelado pelo doador (somente portabilidade).
ACCOUNT_CLOSURE	Esse tipo de cancelamento ocorre caso uma conta seja encerrada e esta possua chaves com pedido de portabilidade em aberto.
FRAUD	Cancelado pelo doador (somente posse).
DEFAULT_OPERATION	Cancelado pelo sistema. Esse tipo de cancelamento ocorre quando o pedido completa sete dias com o status WAITING_RESOLUTION (somente para portabilidade).

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 reinvindicação não encontrado.

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

Eventos

Este endpoint não possui eventos relacionados a ele.