Cancelamento de um pedido de reivindicação
O endpoint de cancelamento de pedido de reivindicação pode ser utilizado tanto pelo doador quanto pelo reivindicador da chave quando houver intenção de cancelar um pedido de reivindicação de posse ou de portabilidade.
Pré-requisitos
Para que seja possível utilizar este endpoint, é necessário que:
- O pedido de reivindicação apresente o status WAITING_RESOLUTION;
- O parceiro possua o código gerado na criação do código TOTP (em caso de cancelamento de pedido reivindicação de chaves do tipo e-mail e telefone por parte do doador).
Requisição (Request)
Requisição HTTP
POST https://sandbox.hiperbanco.com.br/pix/pix-key-claims/{{pixKeyClaimId}}/cancel--request POST 'https://sandbox.hiperbanco.com.br/pix/pix-key-claims/{{pixKeyClaimId}}/cancel' \
--header 'version: cutting-edge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
--data-raw '{
"totpCode": "524715"
}'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 / Query)
No path desta requisição envie os seguintes campos:
| Nome | Tipo | Descrição | Especificação |
|---|---|---|---|
pixKeyClaimId | path | Obrigató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:
| Campo | 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[].cancelReason | string | Motivo do cancelamento do pedido de portabilidade ou posse. |
{
"data": {
"pixKeyClaims": [
{
"id": "f9a1b2c3-4d5e-6789-90ab-cdef12345678",
"type": "OWNERSHIP",
"status": "CANCELED",
"cancelReason": "FRAUD",
"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. |
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. |
| 422 | CLAIM_RESOLUTION_PERIOD_NOT_ENDED | For claim periods, PSP donor cannot confirm prior to the end of the resolution period. | Após o período informado no campo resolutionLimitDate, não é possível solicitar o cancelamento do pedido de reivindicação. |
| 422 | CLAIM_COMPLETION_PERIOD_NOT_ENDED | For ownership claim, if the PSP claimant attempts to terminate before the termination period ends. | Para reivindicação de posse, caso o reclamante do PSP tente encerrar antes do término do período de rescisão. |
| 422 | CLAIM_STATUS_DOES_NOT_ALLOW_CANCELATION | Current claim status does not allow cancelation. | O status atual da reivindicação não permite o cancelamento. |
| 422 | INVALID_CLAIM_CANCEL_REASON | Claim cancel reason is invalid. | O motivo do cancelamento da reivindicação é inválido. |
| 422 | CLAIM_ALREADY_CANCELED | Claim already canceled. | Pedido de reivindicação já cancelado. |
| 422 | INVALID_STATUS_TO_CANCEL_PORTABILITY_CLAIM | Portability cannot be canceled when status is different than WAITING_RESOLUTION or CONFIRMED | O pedido de reivindicação de portabilidade não pode ser cancelado se o status for diferente de WAITING_RESOLUTION ou CONFIRMED. |
| 422 | INVALID_STATUS_TO_CANCEL_OWNERSHIP_CLAIM | Ownership claim cannot be canceled when status is different than WAITING_RESOLUTION, CONFIRMED or WAITING_VALIDATION | O pedido de reivindicação de posse não pode ser cancelado se o status for diferente de WAITING_RESOLUTION, CONFIRMED ou WAITING_VALIDATION. |
| 422 | CANCELATION_REASON_NOT_INFORMED | Cancelation reason not informed. | Motivo do cancelamento não informado. |
| 422 | CANCELATION_REASON_INVALID_TO_PORTABILITY_CLAIM | Cancelation reason is invalid to portability claim. | O motivo do cancelamento é inválido para a reivindicação de portabilidade. |
| 422 | PORTABILITY_CLAIM_STATUS_DOES_NOT_ALLOW_CANCELATION | Current portability claim status does not allow cancelation. | O status atual do pedido de reivindicação de portabilidade não permite o cancelamento. |
| 422 | OWNERSHIP_CLAIM_STATUS_DOES_NOT_ALLOW_CANCELATION | Current ownership claim status does not allow cancelation. | O status atual da reivindicação de posse não permite o cancelamento. |
| 422 | CANCELATION_REASON_INVALID_TO_OWNERSHIP_CLAIM | Cancelation reason is invalid to ownership claim. | O motivo do cancelamento é inválido para reivindicação de posse. |
| 422 | PORTABILITY_CLAIM_RESOLUTION_DATE_NOT_ENDED | Portability claim resolution date not ended to use cancel reason DEFAULT_OPERATION. | A data de resolução da reivindicação de portabilidade não terminou para que se possa usar o motivo de cancelamento DEFAULT_OPERATION. |
| 422 | CLAIM_CAN_ONLY_BE_CANCELED_BY_CLAIMER_OR_DONOR | Portability claim and ownership claim can only be canceled by claimer or donor. | O pedido de reivindicação de portabilidade e o pedido de reivindicação de posse só podem ser cancelados pelo doador. |
| 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_CANCELED | O processo de reivindicação foi cancelado. |
Updated 29 days ago
Did this page help you?