Confirmação de um pedido de reivindicação

stable

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.

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

PATCH https://api-mtls.sandbox.bankly.com.br/pix/claims/{claimId}/confirm
--request PATCH \
--url 'https://api-mtls.sandbox.bankly.com.br/pix/claims/{{claimId}}/confirm' \ 
--header 'api-version: 1' \ 
--header 'x-bkly-pix-user-id: {{DOCUMENT_NUMBER}}' \ 
--header 'Content-Type: application/json' \ 
--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:

ScopeDescrição
pix.claims.confirmConcede acesso para confirmar um pedido de reivindicação.

Cabeçalhos (Headers)

NomeDescriçãoEspecificação
api-versionObrigatório. Versão da API. Atualmente estamos na versão 1.0.
AuthorizationObrigatório. Token de autorização do tipo Bearer.
x-bkly-pix-user-idObrigatório. Número do documento do usuário que está fazendo a requisição.Insira somente números, sem formatação.

Parâmetros da rota (Path)

No path desta requisição envie os seguintes campos:

NomeTipoDescrição
claimIdpathObrigató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:

NomeTipoDescrição
reasonstringObrigatório. Motivo pelo qual a confirmação está ocorrendo, que nesse caso deverá ser preenchido com "DONOR_REQUEST" (solicitação do cliente).
{ 
  "reason": "DONOR_REQUEST" 
}

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:

NomeTipoDescrição
claimIdstringIdentificaçã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.
typestringTipo de reivindicação, que pode ser "PORTABILITY" (portabilidade) ou "OWNERSHIP" (posse).
addressingKeyobjectObjeto que contém informações sobre a chave de endereçamento.
addressingKey.typestringTipo de chave, o qual pode ser "CPF", "CNPJ", "PHONE" ou "EMAIL".
addressingKey.valuestringValor da chave.
claimerobjectObjeto que contém informações sobre o banco a conta do reivindicador.
claimer.branchstringNúmero da agência.
claimer.numberstringNúmero da conta.
claimer.bankobjectObjeto que contém informações sobre o banco do reivindicador.
claimer.bank.ispbstringISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco reivindicador.
donorobjectObjeto que contém informações sobre a conta do doador.
donor.branchstringNúmero da agência.
donor.numberstringNúmero da conta.
donor.bankobjectObjeto que contém informações sobre o banco do doador.
donor.bank.ispbstringISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco do doador.
statusstringSituação do pedido de reivindicação.
previousStatusstringStatus que o pedido de reinvindicação apresentava em etapa anterior.
confirmReasonstringMotivo 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).
confirmedBystringAutor da confirmação do pedido de portabilidade ou posse, o qual pode ser “CLAIMER” (Reivindicador), “DONOR” (Doador) ou “SYSTEM” (quando o sistema confirma a doação de uma chave que já completou 15 dias em WAITING_RESOLUTION - somente em caso de posse).
createdAtstringData de criação do pedido de reivindicação, no formato ISO 8601 - UTC.
updatedAtstringData de atualização do pedido de reivindicação, no formato ISO 8601 - UTC.
resolutionLimitDatestringData limite para o doador de portabilidade realizar ações, como concluir ou cancelar o processo de portabilidade, no formato ISO 8601 - UTC.
conclusionLimitDatestringData 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.
confirmedAtstringData de confirmação do pedido de reivindicação, no formato ISO 8601 - UTC.

🚧

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.

{
    "claimId": "265a48f8-8cb3-4cf4-9170-c65fd83fccc3",
    "type": "OWNERSHIP",
    "addressingKey": {
        "type": "PHONE",
        "value": "+5531293323080"
    },
    "claimer": {
        "branch": "0001",
        "number": "15164",
        "bank": {
            "ispb": "13140088"
        }
    },
    "donor": {
        "branch": "1",
        "number": "422316",
        "bank": {
            "ispb": "13140088"
        }
    },
    "status": "CONFIRMED",
    "previousStatus": "WAITING_RESOLUTION",
    "confirmReason": "DONOR_REQUEST",
    "confirmedBy": "DONOR",
    "createdAt": "2023-05-22T19:48:06.921+00:00",
    "updatedAt": "2023-05-22T19:54:06.1800233Z",
    "resolutionLimitDate": "2023-05-29T19:47:00+00:00",
    "conclusionLimitDate": "2023-06-05T19:47:00+00:00",
    "confirmedAt": "2023-05-22T19:54:06.1800232Z"
}

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 ConclusionLimitDate 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 que chave foi transferida para o Bankly.

👍

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 codeCódigoMensagemDescrição
400USER_ID_REQUIREDEnsure that the x-bkly-pix-user-id header was provided.Certifique-se de que o header x-bkly-pix-user-id foi informado.
404CLAIM_NOT_FOUNDClaim not found.Pedido de reinvindicação não encontrado.
422CLAIM_CANNOT_BE_CONFIRMED_BY_CLAIMERClaim cannot be confirmed by claimer.A reivindicação não pode ser confirmada pelo reivindicador.
422CLAIM_STATUS_DOES_NOT_ALLOW_CONFIRMATIONReceived claim status does not allow confirmation.O status não permite realizar a confirmação.
422CLAIM_CAN_ONLY_BE_CONFIRMED_BY_DONOR_ACCOUNT_HOLDERPortability 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.
422CLAIM_ALREADY_CONFIRMEDClaim already confirmed.A reivindicação já foi confirmada.
422INVALID_STATUS_TO_CONFIRM_CLAIMClaim cannot be confirmed when status is different than WAITING_RESOLUTIONEsse status não permite realizar a confirmação da reivindicação.
422CONFIRMATION_REASON_NOT_INFORMEDConfirmation reason not informed.A razão da confirmação não foi informada.
422CONFIRMATION_REASON_INVALID_TO_PORTABILITY_CLAIMConfirmation reason is invalid to portability claim.A razão da confirmação é inválida para a reivindicação de portabilidade.
422INVALID_STATUS_TO_CONFIRM_OWNERSHIP_CLAIMOwnership claim cannot be confirmed when status is different than WAITING_RESOLUTIONNão é possível realizar a confirmação da reivindicação de posse quando o status é diferente de WAITING_RESOLUTION ou CONFIRMED.
422CONFIRMATION_REASON_INVALID_TO_OWNERSHIP_CLAIMConfirmation reason is invalid to ownership claim.A razão da confirmação é inválida para reivindicação de posse.
422OWNERSHIP_CLAIM_RESOLUTION_DATE_NOT_ENDEDOwnership 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.
422MAXIMUM_ENTRIES_COUNT_REGISTERED_FOR_CLAIMERAccount has reached the maximum entries count registered.Número de vínculos associados à conta transacional excedeu o limite máximo.
422REQUEST_NOT_ALLOWED_OUT_OF_BUSINESS_PERIODRequest 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 eventoDescrição
PIX_CLAIM_WAS_CONFIRMEDO pedido de reivindicação foi confirmado.

Copyright © 2021 Acesso Soluções de Pagamento S.A - Todos os direitos reservados