Quais são as principais alterações introduzidas pela API v2 do DICT?
As principais mudanças trazidas pela API v2 são:
· Adição do novo endpoint de marcação de fraude transacional (createFraudMarker);
· Novos contadores antifraude retornados pelo DICT na consulta de chaves (getEntry) e na consulta de informações de segurança (getEntryStatistics e getPersonStatistics);
· Novos campos na abertura (causa da fraude - SituationType) e no fechamento (tipo da fraude - FraudType) da notificação de infração;
Existe algum roteiro de testes que devem ser executados pelos PSPs para a API v2?
Não existe um roteiro de testes obrigatórios a ser seguido. No entanto, recomendamos fortemente que o PSP teste cada uma das funcionalidades trazidas pela API v2 descritas na resposta da pergunta anterior.
Qual a diferença entre a notificação de infração para marcação de fraude transacional da API v2 e a notificação de infração com motivo FRAUD da API v1?
A notificação de infração para marcação de fraude transacional deve ser usada nos casos em que o PSP deseja apenas marcar o CPF ou o CNPJ de um usuário que seja seu cliente e que esteja envolvido em algum episódio de fraude relacionado a uma transação Pix específica. Ela precisa apenas ser criada pelo participante do Pix através do endpoint createFraudMarker, não necessitando de análise pelo outro PSP.
A notificação de infração com motivo fraude da API v1 também possui como único objetivo a marcação do usuário, porém ela exige que o outro PSP envolvido na transação aceite ou rejeite a notificação. Na API v2, quando o PSP desejar apenas marcar o usuário de outro participante, ele deverá abrir uma notificação de infração para solicitação de devolução, ainda que não exista a expectativa de reaver os recursos.
Como funcionará o período de convivência das APIs v1 e v2?
A fim de permitir que sejam feitos ajustes nos modelos e processos antifraude dos participantes, as versões v1 e v2 da API do DICT ficarão disponíveis em produção durante um período de 3 meses a partir da ativação da v2.
O processo de ativação da v2 e desativação da v1 possui 3 marcos importantes:
· 05 Novembro 2023 - Ativação em produção da versão 2.0 da API do DICT.
A API v1 continuará em funcionamento normal, sem nenhuma quebra de compatibilidade.
· 12 Novembro 2023 - Desativação do endpoint createInfractionReport da API v1.
No início do dia, o endpoint de criação de notificação de infração da API v1 será desativado. Requisições POST feitas no endpoint /v1/infraction-reports/ receberão resposta de erro com status 510.
Todo restante da API v1 continuará funcionando, sem quebra de compatibilidade.
· 04 Fevereiro 2024 - Desativação completa da API v1.
No início do dia, a API v1 será completamente desativada. Qualquer requisição feita em endpoints /v1/ receberá resposta de erro com status 400. Todas as requisições deverão ser feitas em endpoints da API v2.
Notificações de infração criadas na API v1 estarão visíveis na v2?
A notificações de infração criadas na API v1 para REFUND_REQUEST e REFUND_CANCELLED estarão visíveis na API v2 e poderão ser modificadas por operações da API v2. Da mesma forma, notificações de infração criadas na v2 estarão visíveis e poderão ser modificadas por operações na API v1 durante o período de convivência.
As notificações de infração do tipo FRAUD criadas na v1 não serão visíveis na v2 nos endpoints Listar Notificações de Infração - GET /api/v2/infraction-reports/ ou Consultar Notificações de Infração - GET /api/v2/infraction-reports/{InfractionReportId}/. Na v2, será retornado status 410 Gone caso se tente fazer alguma operação e elas não aparecerão na listagem.
Notificações de infração do tipo FRAUD criadas na API v1 que tenham sido fechadas devem ser entendidas como marcações de fraude na API v2. Elas poderão ser consultadas e canceladas nos endpoints Consultar Marcação de Fraude - /api/v2/fraud-markers/{id} e Cancelar Marcação de Fraude - /api/v2/fraud-markers/{id}/cancel usando id da notificação de infração.
Notificações de infração do tipo FRAUD criadas na API v1 e que estejam em andamento (status OPEN ou ACKNOWLEDGED) deverão necessariamente ser fechadas ou canceladas via API v1 antes do seu desligamento.
Como funcionarão os dados estatísticos durante o período de convivência?
Durante o período de convivência, os contadores das APIs v1 e v2 estarão ativos.
Independentemente se o evento foi originado em requisição feita pela v1 ou v2, contadores que tenham a mesma semântica na v1 e v2 serão sensibilizados igualmente.
As marcações de fraude geradas na API v1 deixarão de existir na API v2?
Não. Na API v2, uma notificação de infração do tipo FRAUD criada na v1 poderá ser consultada utilizando o endpoint “consultar marcação de fraude” (GetFraudMarker), passando como parâmetro o ID da notificação. Na API v2, marcações de fraude criadas na v1 estarão refletidas no contador “notificações de infração confirmadas sem identificação de tipo de fraude” (campo UnknownFrauds na API v2). Os contadores “quantidade de notificações ainda não fechadas no momento da consulta” (OpenReports) e “notificações de infração rejeitadas totais” (RejectedReports) também considerarão em seus cálculos as notificações criadas na API v1.
Na API v2, as operações de listar (ListInfractionReports) e consultar notificações de infração (GetInfractionReport) só retornarão as notificações de infração do tipo REFUND_REQUEST e REFUND_CANCELLED, independentemente se criadas na v1 ou v2.
Qual é o prazo de análise para uma notificação de infração para marcação de fraude transacional?
Notificações de infração para marcação de fraude transacional, abertas através do endpoint FraudMarker, terão seu fluxo encerrado no mesmo momento de sua criação, pois não é necessário análise pelo PSP da contraparte. Lembrando que o PSP só pode abrir uma notificação de infração para marcação de fraude contra o seu próprio cliente e que esteja envolvido em algum episódio de fraude relacionado a uma transação Pix específica.
Notificações de infração para solicitação de devolução ou para cancelamento de devolução continuarão tendo prazo de análise pelo PSP da contraparte de 7 dias.
Como deverão ser tratadas as notificações de infração com motivo Fraude abertas na API v1?
O PSP deverá ser capaz de consultar, receber e analisar na API v1 as notificações de infração do tipo FRAUD, criadas até o dia 12/11, pois as operações relacionadas a esse tipo de notificação não estarão disponíveis na API v2.
Como poderei tratar, após o dia 12/11, as notificações de infração do tipo FRAUD abertas na API v1?
O PSP deverá tratar normalmente as notificações de infração do tipo FRAUD abertas na API v1. O único endpoint da API v1 que será desativado no dia 12/11 será o de criação (createInfractionReport). Os demais endpoints da API v1 (listar, consultar, receber, cancelar e fechar) permanecerão ativos até 04/02/24.
Quando poderei migrar completamente para a API v2?
Após o dia 12/11/23, não havendo mais notificações de infração do tipo FRAUD pendentes de recebimento ou de análise, o PSP poderá migrar totalmente para a API v2.
Na abertura da notificação de infração para cancelamento da devolução, o que deve ser informado no campo "SituationType"?
Uma notificação de infração para cancelamento de devolução deverá ser sempre preenchida na abertura com o campo “Causa da fraude” (SituationType) igual a “outros” e, portanto, o campo “Comentários” (ReportDetails) deverá ser preenchido com a explicação do caso em questão.
Como a notificação de infração do tipo FRAUD deixará de existir na API v2, qual fluxo deverei seguir para apenas marcar uma chave ou um usuário de outro PSP envolvido na transação, onde não há expectativa de recuperação dos recursos?
Ainda que deseje apenas marcar o usuário de outro participante, o PSP deve usar a notificação de infração associada a uma solicitação de devolução para o mesmo propósito. Mesmo que a solicitação de devolução seja rejeitada por qualquer motivo, a marcação de fraude será mantida.
Por quanto tempo as marcações de fraude criadas na API v1 ficarão ativas?
As marcações de fraude (tanto as realizadas API v1 quanto as novas da API v2) serão exibidas para os prazos de 90 dias, 12 meses e 60 meses. Portanto, as marcações realizadas há mais 60 meses não serão exibidas pelo DICT.
Poderei marcar mais de uma vez o mesmo usuário através da marcação de fraude transacional?
Sim, no entanto, é importante destacar que cada transação Pix só pode ter uma única marcação de fraude associada.
Após a identificação da fraude, realização do bloqueio cautelar e da devolução dos recursos, como devo proceder para marcar o meu cliente?
O PSP deve utilizar a notificação de infração para marcação de fraude transacional (createFraudMarker) para marcar CPFs, CNPJs e chaves de usuários envolvidos em fraudes relacionadas a transações Pix e que sejam clientes do próprio participante que criar a marcação.
Qual é o prazo final para migração para a API v2?
O período de convivência entre as APIs v1 e v2 durará até o dia 04/02/24. Essa é a data limite para migração para a API v2.
Quando será descontinuada a API v1?
A partir do dia 12/11/23 as notificações de infração deverão ser abertas exclusivamente através da API v2. Os demais serviços da API v1 serão desativados no dia 04/02/24.
Por ter o mesmo mecanismo de limitação para os participantes aplicado à operação getEntry, a operação getEntryStatistics consumirá fichas do mesmo balde?
Não, apesar das operações getEntry e getEntryStatistics possuírem mecanismos de limitação idênticos, cada uma consumirá fichas de baldes específicos.
Na operação de consulta de chaves getEntry, o que acontece se o parâmetro opcional IncludeStatistics for omitido?
Através do parâmetro opcional IncludeStatistics, o PSP poderá definir se as informações de segurança da chave deverão ser inseridas na resposta do DICT. Caso o parâmetro seja omitido, apenas os dados cadastrais vinculados à chave serão retornados pelo DICT.
Por que não existe o campo Causa da Fraude (SituationType) na marcação de fraude transacional?
O campo SituationType, preenchido pelo PSP que abre a notificação, tem o objetivo principal de auxiliar o PSP que vai analisar a fraude. Ele não entra nas estatísticas do DICT. Como na marcação de fraude transacional não existe a necessidade de análise pela contraparte, não há razão para a existência desse campo.
Já o campo FraudType é preenchido pelo PSP que fecha a notificação e é contabilizado nas estatísticas de segurança. Esse campo é obrigatório na marcação de fraude, pois o PSP que abriu o a notificação é o mesmo PSP que a encerra.
O contador de liquidações como recebedor (Settlements) será corrigido na API v2?
Sim. Porém, a contagem desse contador será reiniciada a partir da entrada em produção da API v2. Ou seja, o contador Settlements exibirá o volume de transações recebidas pelo usuário ou pela chave consultada que tenham ocorrido a partir do dia 05/11/23.
Todos os contadores da API v2 estarão disponíveis a partir do dia 05/11?
O contador “quantidade de contas distintas às quais a chave esteve associada” (DistinctAccounts) não estará disponível a partir do dia 05/11 para utilização pelos participantes. Até que a sua atualização esteja finalizada ele exibirá sempre o valor zero. A previsão é que o contador DistinctAccounts esteja disponível a partir do dia 26/11/23.
Os demais contadores da API 2.0 do DICT estarão atualizados e completamente funcionais a partir do dia 05/11/23.