A confirmação de um pedido de reivindicação é uma etapa exclusiva do fluxo de doação de chaves. Ela ocorre quando outra instituição financeira faz ao cliente de nosso parceiro um pedido de reivindicação de portabilidade ou posse de uma chave. Caso o cliente opte por ceder a chave solicitada, será necessário confirmar o pedido. Ao confirmar um pedido de reivindicação, o vínculo da chave com o doador é removido. > ⚠️ Importante > > Os pedidos de reivindicação de portabilidade ou posse são comunicados ao parceiro via eventos de webhoook. Para receber esses eventos, é preciso realizar a configuração dos webhooks. Se desejar, o parceiro também poderá utilizar o endpoint de [consulta de pedidos](https://docs.hiperbanco.com.br/docs/consulta-dos-pedidos-de-reivindicacao). ## **Pré-requisito** Para que seja possível utilizar este endpoint, é necessário que: * O cliente de nosso parceiro tenha recebido um pedido de reivindicação de portabilidade ou posse de uma chave. ## **Requisição (Request)** ### Requisição HTTP ```http POST https://sandbox.hiperbanco.com.br/pix/pix-key-claims/{{pixKeyClaimId}}/confirm ``` ```curl --request POST 'https://sandbox.hiperbanco.com.br/pix/pix-key-claims/{{pixKeyClaimId}}/confirm' \ --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) No path desta requisição envie os seguintes campos: | Nome | Tipo | Descrição | | ------------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | pixKeyClaimId | path | Obrigatório. Identificador único do pedido. Esse valor é retornado na [criação de pedido de reivindicação](https://docs.hiperbanco.com.br/docs/criacao-de-pedido-de-reivindicacao), no evento [PIX\_CLAIM\_WAS\_CONFIRMED](https://docs.hiperbanco.com.br/docs/eventos-pix#/pix_claim_was_confirmed) e na [consulta dos pedidos de reivindicação](https://docs.hiperbanco.com.br/docs/consulta-dos-pedidos-de-reivindicacao). | ### Corpo da requisição (Body) Não é necessário enviar campos no body desta requisição. ## **Resposta (Response)** O status code 200 indicará que o pedido foi confirmado com sucesso.Sendo bem-sucedido, o retorno irá trazer 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).

> ⚠️ Importante > > Os pedidos de reivindicação de portabilidade ou posse são comunicados ao parceiro via eventos de webhoook. Para receber esses eventos, é preciso realizar a configuração dos webhooks. Se desejar, o parceiro também poderá utilizar o endpoint de consulta de pedidos. ```json { "data": { "pixKeyClaims": [ { "id": "f9a1b2c3-4d5e-6789-90ab-cdef12345678", "type": "OWNERSHIP", "status": "CONFIRMED", "confirmReason": "DONOR_REQUEST", "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": "13140088" } }, "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. | ## **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. | | 422 | CLAIM\_CANNOT\_BE\_CONFIRMED\_BY\_CLAIMER | Claim cannot be confirmed by claimer. | A reivindicação não pode ser confirmada pelo reivindicador. | | 422 | CLAIM\_STATUS\_DOES\_NOT\_ALLOW\_CONFIRMATION | Received claim status does not allow confirmation. | O status não permite realizar a confirmação. | | 422 | CLAIM\_CAN\_ONLY\_BE\_CONFIRMED\_BY\_DONOR\_ACCOUNT\_HOLDER | Portability claim and ownership claim only can be confirmed by donor account holder. | A reivindicação de portabilidade ou de posse só pode ser confirmada pelo titular da conta do doador. | | 422 | CLAIM\_ALREADY\_CONFIRMED | Claim already confirmed. | A reivindicação já foi confirmada. | | 422 | INVALID\_STATUS\_TO\_CONFIRM\_CLAIM | Claim cannot be confirmed when status is different than WAITING\_RESOLUTION | Esse status não permite realizar a confirmação da reivindicação. | | 422 | CONFIRMATION\_REASON\_NOT\_INFORMED | Confirmation reason not informed. | A razão da confirmação não foi informada. | | 422 | CONFIRMATION\_REASON\_INVALID\_TO\_PORTABILITY\_CLAIM | Confirmation reason is invalid to portability claim. | A razão da confirmação é inválida para a reivindicação de portabilidade. | | 422 | INVALID\_STATUS\_TO\_CONFIRM\_OWNERSHIP\_CLAIM | Ownership claim cannot be confirmed when status is different than WAITING\_RESOLUTION | Não é possível realizar a confirmação da reivindicação de posse quando o status é diferente de WAITING\_RESOLUTION ou CONFIRMED. | | 422 | CONFIRMATION\_REASON\_INVALID\_TO\_OWNERSHIP\_CLAIM | Confirmation reason is invalid to ownership claim. | A razão da confirmação é inválida para reivindicação de posse. | | 422 | OWNERSHIP\_CLAIM\_RESOLUTION\_DATE\_NOT\_ENDED | Ownership claim resolution date not ended to use confirm reason DEFAULT\_OPERATION. | Como a data de resolução da reivindicação de posse ainda não expirou, não é possível utilizar a razão DEFAULT\_OPERATION. | | 422 | MAXIMUM\_ENTRIES\_COUNT\_REGISTERED\_FOR\_CLAIMER | Account has reached the maximum entries count registered. | Número de vínculos associados à conta transacional excedeu o limite máximo. | | 422 | REQUEST\_NOT\_ALLOWED\_OUT\_OF\_BUSINESS\_PERIOD | Request not allowed out of business period. | Serviço indisponível ou em manutenção. | 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\_CONFIRMED](https://docs.hiperbanco.com.br/docs/eventos-pix#/pix_claim_was_confirmed) | O pedido de reivindicação foi confirmado. |