Manual
Start typing to search…

Completando o pedido de reivindicação

Depois que a requisição de reivindicação de portabilidade ou posse de chave é enviada, a instituição que a recebeu dará um retorno ao Hiperbanco, confirmando ou não a doação da chave.

Caso o parceiro tenha reivindicado a portabilidade de uma chave, o pedido sempre será completado automaticamente após a confirmação do recebimento por parte da instituição doadora.

Porém, se o parceiro reivindicou a posse de uma chave, ele deverá completar o pedido por meio do endpoint a seguir.

Pré-requisitos

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

  • A reivindicação de posse apresente o status CONFIRMED. O status pode ser verificado por meio do endpoint Consulta dos pedidos de reivindicação;
  • O parceiro possua o código gerado na criação do código TOTP (em caso de reivindicação de chaves do tipo e-mail e telefone).

Requisição (Request)

Requisição HTTP

POST  https://sandbox.hiperbanco.com.br/pix/pix-key-claims/{{pixKeyClaimId}}/complete
--request POST 'https://sandbox.hiperbanco.com.br/pix/pix-key-claims/{{pixKeyClaimId}}/complete' \
--header 'version: cutting-edge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
--data-raw '{
  "totpCode": "524715"
}'

Cabeçalhos (Headers)

NomePropriedadeDescrição
versioncutting-edgeEssa propriedade garante que o response da API seja retornado no formato JSON
AuthorizationBearer tokenObrigatório. Token de autorização do tipo Bearer.
❗️

Atenção

Somente será possível completar o pedido de posse de chaves do tipo e-mail e telefone após a validação da identidade do cliente via código TOTP.

Parâmetros da rota (Path)

No path desta requisição envie o seguinte campo:

NomeTipoDescrição
pixKeyClaimIdpathObrigatório. Identificador único do pedido. Esse valor é retornado na criação de pedido de reivindicação, no evento PIX_CLAIM_WAS_CONFIRMED e na consulta dos pedidos de reivindicação.

Corpo da requisição (Body)

No body, envie os seguintes campos em formato JSON:

Nome

Tipo

Descrição

Especificação

totpCode

string

Obrigatório. Código enviado pela instituição financeira para confirmar a identidade de seu cliente Esse código pode ser enviado por e-mail ou SMS, e o cliente deverá informá-lo para ser validado e poder dar continuidade à ação que iniciou.

—

Resposta (Response)

O status code 200 indicará que o pedido foi completado 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).

{
  "data": {
    "pixKeyClaims": [
      {
        "id": "f9a1b2c3-4d5e-6789-90ab-cdef12345678",
        "type": "OWNERSHIP",
        "status": "COMPLETED",
        "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

StatusDescrição
OPENSolicitação aberta pelo reivindicador, mas ainda não recebida pelo doador.
WAITING_RESOLUTIONA reivindicação já foi recebida pelo doador e está aguardando a resolução.
CONFIRMEDO 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_VALIDATIONApó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).
CANCELEDO 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.
COMPLETEDO 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 codeCódigoMensagemDescrição
422INVALID_CLAIM_OPERATIONThe current claim status does not allow the operation to be done.O status atual da reivindicação não permite realizar essa operação.
422CLAIM_STATUS_DOES_NOT_ALLOW_COMPLETIONCurrent claim status does not allow completion.O status atual da reivindicação não permite que ela seja completada.
422CLAIM_CANNOT_BE_COMPLETED_BY_DONORClaim cannot be completed by donor.A reivindicação não pode ser completada pelo doador.
422CLAIM_CAN_ONLY_BE_COMPLETED_BY_CLAIMER_ACCOUNT_HOLDERPortability claim and ownership claim only can be completed by claimer account holder.A reivindicação de posse só pode ser completada pelo titular da conta do reivindicador.
422CLAIM_ALREADY_COMPLETEDClaim already completed.A reivindicação já foi completada.
422INVALID_STATUS_TO_COMPLETE_PORTABILITYPortability cannot be completed when status is different than CONFIRMEDA reivindicação de portabilidade não pode ser completada quando o status for diferente de CONFIRMED.
422INVALID_STATUS_TO_COMPLETE_OWNERSHIPOwnership cannot be completed when status is different than WAITING_VALIDATIONA reivindicação de posse não pode ser completada quando o status for diferente de WAITING_VALIDATION.
422OWNERSHIP_CLAIM_CONCLUSION_DATE_NOT_ENDEDOwnership claim conclusion date not ended.A data de conclusão da reivindicação de posse não foi encerrada.

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 eventoDescrição
PIX_CLAIM_WAS_COMPLETEDO processo de reivindicação foi concluído.

Updated 26 days ago