Cancelamento de um pedido de reivindicação
stable
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é-requisito
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 hash 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
Requisição HTTP
PATCH https://api-mtls.sandbox.bankly.com.br/pix/claims/{CLAIMID}/cancel
--curl--request PATCH \
--url 'https://api-mtls.sandbox.bankly.com.br/pix/claims/{{CLAIMID}}/cancel' \
--header 'api-version: 1.0' \
--header 'x-bkly-pix-user-id: {{DOCUMENT_NUMBER}}' \
--header 'Content-Type: application/json' \
--header ' x-bkly-transactional-hash: {{hash}}' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{token}} ' \
--data-raw '{
"reason": "DONOR_REQUEST"
}'
Autorização
Para garantir a segurança nas requisições, todos os endpoints do Bankly utilizam scopes como parte do seu fluxo de autorização.
Esta requisição requer o scope descrito a seguir:
| Scope | Descrição |
|---|---|
pix.claims.cancel | Concede acesso para cancelar um pedido de reivindicação. |
Cabeçalhos (Headers)
| Nome | Descrição |
|---|---|
api-version | Obrigatório. Versão da API. Atualmente estamos na versão 1.0. |
Authorization | Obrigatório. Token de autorização do tipo Bearer. |
x-bkly-pix-user-id | Obrigatório. Número do documento do cliente que está fazendo a requisição. Insira apenas números, sem formatação. |
x-bkly-transactional-hash | O envio desse campo no header da requisição é obrigatório apenas para reivindicação de chaves do tipo e-mail e telefone. Ele deve ser preenchido com o hash gerado na criação do código TOTP. |
Parâmetros da rota (Path)
No path desta requisição envie o seguinte campo:
| Nome | Tipo | Descrição |
|---|---|---|
claimId | 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 o seguinte campo em formato JSON:
| Nome | Tipo | Descrição |
|---|---|---|
reason | string | Obrigatório. Motivo do cancelamento do pedido. Esse campo deve ser preenchido com "DONOR_REQUEST" (solicitação do doador) ou "CLAIMER_REQUEST" (solicitação do reivindicador) para cancelar um pedido de reivindicação de portabilidade. Para pedidos de cancelamento de reivindicação de posse, esse campo deve ser preenchido com "FRAUD". |
{
"reason": "DONOR_REQUEST"
}
Resposta (Response)
O status code 200 indicará que o pedido foi cancelado com sucesso.
Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:
| Nome | Tipo | Descrição |
|---|---|---|
claimId | 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. |
type | string | Tipo de reivindicação, que pode ser PORTABILITY (portabilidade) ou OWNERSHIP (posse). |
addressingKey | object | Objeto que contém os dados da chave de endereçamento. |
addressingKey.type | string | Tipo de chave, o qual pode ser: CPF, CNPJ, PHONE e EMAIL. |
addressingKey.value | string | Valor da chave. |
claimer | object | Objeto que contém os dados do banco e da conta do reivindicador. |
claimer.branch | string | Número da agência bancária. |
claimer.number | string | Número da conta. |
claimer.bank | object | Objeto que contém os dados do banco do reivindicador. |
claimer.bank.ispb | string | ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco. |
donor | object | Objeto que contém os dados do banco e da conta do doador. |
donor.branch | string | Número da agência bancária. |
donor.number | string | Número da conta. |
donor.bank | object | Objeto que contém os dados do banco do doador. |
donor.bank.ispb | string | ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco. |
status | string | Situação do pedido de reivindicação, o qual pode ser: OPEN (aberto), WAITING_RESOLUTION (aguardando resolução), CONFIRMED (confirmado), CANCELLED (cancelado) ou COMPLETED (completado). |
previousStatus | string | Status que o pedido de reinvindicação apresentava em etapa anterior. |
cancelReason | string | Motivo do cancelamento do pedido de reinvindicação. |
canceleddBy | string | Autor do cancelamento do pedido de reinvindicação, que pode ser: DONOR (doador), CLAIMER (reivindicador) ou SYSTEM (apenas em caso de portabilidade, quando o pedido completa sete dias com o status WAITING_RESOLUTION, o sistema realiza o cancelamento). |
createdAt | string | Data de criação do pedido de reivindicação, no formato aaaa-mm-ddTHH:mm:ss.sssZ. |
updatedAt | string | Data de atualização do pedido de reivindicação, no formato aaaa-mm-ddTHH:mm:ss.sssZ. |
resolutionLimitDate | string | Data limite para o doador de portabilidade realizar ações, como concluir ou cancelar o pedido de reivindicação, no formato aaaa-mm-ddTHH:mm:ss.sssZ. |
conclusionLimitDate | string | Data limite para o doador de posse e o reivindicador (tanto de posse como de portabilidade) confirmarem ou cancelarem o pedido, no formato aaaa-mm-ddTHH:mm:ss.sssZ. |
canceledAt | string | Data de cancelamento do pedido de reivindicação, no formato aaaa-mm-ddTHH:mm:ss.sssZ. |
{
"claimId": "10f810aa-0ff2-4d5a-9eb9-96e539dab7dc",
"type": "OWNERSHIP",
"addressingKey": {
"type": "EMAIL",
"value": "[email protected]"
},
"claimer": {
"branch": "0001",
"number": "15164",
"bank": {
"ispb": "13140088"
}
},
"donor": {
"branch": "0001",
"number": "540108",
"bank": {
"ispb": "13140088"
}
},
"status": "CANCELED",
"previousStatus": "WAITING_RESOLUTION",
"cancelReason": "FRAUD",
"canceledBy": "DONOR",
"createdAt": "2023-01-27T17:47:45.261+00:00",
"updatedAt": "2023-01-27T17:53:30.4030599Z",
"resolutionLimitDate": "2023-02-03T17:47:45.261+00:00",
"conclusionLimitDate": "2023-02-10T17:47:45.261+00:00",
"canceledAt": "2023-01-27T17:53:30.4030598Z"
}
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. |
| 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 que chave foi transferida para o Bankly. |
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 para 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). |
Dica
Para simular uma requisição nesse endpoint, acesse o API Reference.
Erros
Este endpoint pode retornar erros específicos, conforme a tabela a seguir:
| Status code | Código | Descrição |
|---|---|---|
| 400 | USER_ID_REQUIRED | Certifique-se de que o header x-bkly-pix-user-id foi informado. |
| 404 | CLAIM_NOT_FOUND | Pedido de reinvindicação não encontrado. |
| 422 | INVALID_TRANSACTIONAL_HASH | Certifique-se de que o header x-bkly-transactional-hash foi informado. |
| 422 | CLAIM_RESOLUTION_PERIOD_NOT_ENDED | Após o período informado no campo resolutionLimitDate, não é possível solicitar o cancelamento do pedido de reivindicação. |
| 422 | CLAIM_STATUS_DOES_NOT_ALLOW_CANCELATION | O status atual da reivindicação não permite o cancelamento. |
| 422 | INVALID_CLAIM_CANCEL_REASON | O motivo do cancelamento da reivindicação é inválido. |
| 422 | CLAIM_ALREADY_CANCELED | Pedido de reivindicação já cancelado. |
| 422 | INVALID_STATUS_TO_CANCEL_CLAIM | O pedido de reivindicação não pode ser cancelado se o status for diferente de WAITING_RESOLUTION ou CONFIRMED |
| 422 | CANCELATION_REASON_NOT_INFORMED | Motivo do cancelamento não informado. |
| 422 | CANCELATION_REASON_INVALID_TO_PORTABILITY_CLAIM | O motivo do cancelamento é inválido para a reivindicação de portabilidade. |
| 422 | 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 | O status atual da reivindicação de posse não permite o cancelamento. |
| 422 | CANCELATION_REASON_INVALID_TO_OWNERSHIP_CLAIM | O motivo do cancelamento é inválido para reivindicação de posse. |
| 422 | PORTABILITY_CLAIM_RESOLUTION_DATE_NOT_ENDED | 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 | 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 | Serviço indisponível ou em manutenção. |
Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints. Portanto, recomendamos a consulta da documentação de erros, onde é possível encontrar as mensagens comuns em inglês 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 about 2 months ago