O objetivo deste documento é apresentar as especificações técnicas e homologatórias para antifraude nos pagamentos instantâneos, solução desenvolvida e operada pela
Clear que tem o objetivo de auxiliar na avaliação, pelos participantes, da confiabilidade de informações relacionadas aos usuários finais do PIX,
buscando mitigar o risco de fraude em transações no âmbito do PIX.
A plataforma foi elaborada para ser utilizada pelo ecossistema de pagamentos instantâneos brasileiro como um todo, utilizando um conceito de base compartilhada.
Quanto mais participantes estiverem integrados à solução, mais seguro será o sistema. Ao mesmo tempo, permite autonomia e controle total dos participantes
terem sua própria gestão de risco, recebendo os melhores insumos para tomada de decisão
Descrição do Produto
O antifraude PIX foi desenvolvido exclusivamente para auxiliar as Instituições Financeiras na tomada de decisão e avaliação do risco
das informações relacionadas aos processos de criação da chave pix, análise transacional de pagadores e recebedores.
O antifraude PIX realiza esse processo de análise e verificação
do risco utilizando score e regras de decisão:
Score: medida relacionada ao risco de fraude, quanto
maior o número gerado pelo score, maior o risco de fraude.
Regras de Decisão: aplica um conjunto de regras que devem ser atendidas, para uma transação poder ser consideradas válida.
Segurança
Todas as requisições submetidas à nossa API devem ser realizadas através de um token gerado através de um usuário, senha e id da entidade que devem ser fornecidos
pela Clear.
Na autenticação, além do token retornamos seu tempo de expiração. É necessário que contemple no seu desenvolvimento o gerenciamento da vida útil do token
com base nesse tempo de expiração. Só gere um novo token após a expiração do seu token atual.
O acesso aos serviços é feito através de API REST, usando padrões de mercado seguros.
Funcionalidades Disponíveis
Abaixo seguem as funcionalidades disponíveis para utilização no Serviço Antifraude para Pagamentos Instantâneos:
Feedbackfraud: Retroalimentação de marcações de fraudes
AntifraudScore: Geração de Score sobre análise da transação
AntifraudDecision: Geração de Score e Aplicação de Regra sobre análise da transação
Fluxo de Integração
Homologação
Pré-requisitos:
Adesão aos serviços;
Envio dos documentos de Matriz de Funcionalidades, Cadastro de Contatos e Cadastro Técnico para o e-mail suporte.pix@clear.sale;
Após os requisitos acima devidamente atendidos e validados, a Clear enviará o usuário e senha para acesso.
Hostname Homologação:
https://afpi-hmg.sec-hub.com.br
Observação:
Recomendamos não enviar dados produtivos nos testes do ambiente de homologação. Os dados retornados no ambiente de homologação são aleatórios e fictícios.
Produção
Pré-requisitos:
Adesão aos serviços;
Envio dos documentos de Matriz de Funcionalidades, Cadastro de Contatos e Cadastro Técnico para o e-mail suporte.pix@clear.sale;
Após os requisitos acima devidamente atendidos e validados, a Clear enviará o usuário e senha para acesso.
Hostname Produção:
https://afpi.sec-hub.com.br/
Tratamento de Erro
401 - Não autorizado:
Possíveis problemas: erro ao autenticar a requisição. Consulte o valor do token.
400 - BadRequest:
Possíveis problemas: verifique se algum campo no corpo da requisição não está preenchido.
500 - Internal Server Error
Possíveis problemas: algum tipo de problema está afetando o desempenho do servidor que você está tentando acessar.
Swagger
Será possível visualizar as regras no swagger através deste link =>
Autenticação
Este endpoint está disponível na API na seguinte rota "/v1/authentication".
Todas as requisições submetidas à API devem ser realizadas utilizando um token,
gerado a partir de um usuário e senha que serão fornecidos pela ClearSale.
Na autenticação, é retornado o token e seu tempo de expiração em segundos.
É necessário que contemple no seu desenvolvimento o gerenciamento da vida
útil do token com base nesse tempo de expiração.
Somente gere um novo token após a expiração do seu token atual.
Parâmetros
Nome
Valor
Tipo
Obrigatório
Username
usuario_automatico
String
Sim
Password
senha12345
String
Sim
Feedbackfraud - Post - Retroalimentação de marcações de fraude
Este endpoint está disponível na API na seguinte rota
"v1/feedback/frauds".
Tem a finalidade de receber dados relacionados a um alerta de fraude relacionado a
alguma informação do contexto da nossa solução.
Parâmetros
Nome
Valor
Tipo
Obrigatório
participant
87654321
String
Sim
summary
Fraude de roubo de whatsapp
String
Sim
description
Fraude de roubo de whatsapp relatada pelo cliente em XX/YY/ZZZZ, nos ligou informando o modo de operação, o cliente recebeu uma mensagem...
String
Sim
visibility
1
Integer
Sim
referenceDate
2021-12-28T14:49:56.9115638+00:00
String
Sim
status
2
String
Sim
relatedEntries
[object Object]
Object
Sim
relatedTransfers
[object Object]
Object
Sim
RelatedEntries
Nome
Valor
Tipo
Obrigatório
entryId
4cbe1d0332f840c7ae716861dd866a8d
String
Sim
key
[object Object]
Object
Não
account
[object Object]
Object
Não
statistics
[object Object]
Object
Não
RelatedTransfers
Nome
Valor
Tipo
Obrigatório
transferId
4cbe1d0332f840c7ae716861dd866a8d
String
Sim
transactionType
PACS.008
String
Sim
endToEndId
E9999901012341234123412345678900
String
Sim
txId
90000
String
Não
channel
WEB
String
Não
qrCode
[object Object]
Object
Não
urlLink
[object Object]
Object
Sim
recipient
[object Object]
Object
Sim
sender
[object Object]
Object
Sim
currency
BRL
String
Sim
amount
110.55
Number
Sim
referenceDate
2021-12-28T14:49:56.9115638+00:00
String
Sim
QrCode
Nome
Valor
Tipo
Obrigatório
value
"00020101021126440014br.gov.bcb.pix0122fulano2019@example.com5204000053039865802BR5913FULANO DE TAL6008BRASILIA6304DFE3"
AntifraudScore - Post - Geração de Score sobre análise da transação
Este endpoint está disponível na API para seguinte rota
"v1/analysis/antifraudscore".
Tem a finalidade de analisar os dados relacionados entre dois participantes, podendo ser pessoa física o/ou jurídica e
gerar resultados de score de risco de 0 a 1000.
Referente ao score, quanto maior o valor, maior será o risco de fraude e o mesmo vale inversamente.
Obs:
Campos com obrigatoriedade "opcional" caso preenchido, será necessário preencher campos obrigatório que dependam do objeto pai.
O exemplo de retorno está no AntifraudScore - Get.
AntifraudScore - Get - Retorna informação da análise de transações
Este endpoint está disponível na API para seguinte rota
"v1/analysis/antifraudscore/{id}".
Tem a finalidade de buscar o resultado de uma análise feita através do ID de uma análise já feita anteriormente, retornando somente o Score da transação e ScoreComportamental.
AntifraudDecision - Post - Geração de Score e Aplicação de Regra sobre análise da transação
Este endpoint está disponível na API para seguinte rota
"v1/analysis/antifrauddecision".
Tem a finalidade de analisar os dados relacionados entre dois participantes, podendo ser pessoa física o/ou jurídica e
gerar resultados de score de risco de 0 a 1000, bem como, regra aplicada de acordo com o motor de decisão.
Referente ao score, quanto maior o valor, maior será o risco de fraude e o mesmo vale inversamente.
Obs:
Campos com obrigatoriedade "opcional" caso preenchido, será necessário preencher campos obrigatório que dependam do objeto pai.
O exemplo de retorno está no AntifraudDecision - Get.
AntifraudDecision - Get - Retorna informação da análise de transações
Este endpoint está disponível na API para seguinte rota
"v1/analysis/antifrauddecision/{id}".
Tem a finalidade de buscar o resultado de uma análise feita através do ID de uma análise já feita anteriormente, retornando Score calculado por transação e regras que determinou a aprovação (APA) ou reprovação (RPA).