PIX ANTIFRAUDE

Última atualização: 22 de Maio de 2023

Introdução

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" String Sim
dynamicUrl [object Object] Object Não
DynamicUrl
Nome Valor Tipo Obrigatório
url http://bx.com.br/spi/U0VHUkVET1RPVEFMTUVOVEVBTEVBVE9SSU8= String Sim
ip 127.0.0.1 String Sim
UrlLink
Nome Valor Tipo Obrigatório
url http://bx.com.br/spi/U0VHUkVET1RPVEFMTUVOVEVBTEVBVE9SSU8= String Sim
ip 127.0.0.1 String Sim
Recipient
Nome Valor Tipo Obrigatório
account [object Object] Object Sim
statistics [object Object] Object Não
document 45985782000101 String Sim
documentType CNPJ String Sim
name João Silva String Não
tradeName Marca Comercial Exemplo String Não
key [object Object] Object Não
Account
Nome Valor Tipo Obrigatório
participant 56 String Sim
branch 55997874 String Não
accountNumber Brasil String Não
accountType CACC String Não
openingDate 2019-10-18T14:49:56.9115638+00:00 String Sim
Statistics
Nome Valor Tipo Obrigatório
lastUpdated 2021-12-28T14:49:56.9115638+00:00 String Não
counters [Array] String Não
counters[0].FraudEventCounterDto.type CONFIRMED_FRAUDS String Sim
counters[0].FraudEventCounterDto.by KEY String Sim
counters[0].FraudEventCounterDto.d3 3 Integer Não
counters[0].FraudEventCounterDto.d30 4 Integer Não
counters[0].FraudEventCounterDto.m6 5 Integer Não
Key
Nome Valor Tipo Obrigatório
value 10770753000130 String Sim
type CNPJ String Sim
creationDate 2019-11-18T03:00:00+00:00 String Não
keyOwnershipDate 2019-11-18T03:00:00+00:00 String Não
openClaimCreationDate 2019-11-18T03:00:00+00:00 String Não
Sender
Nome Valor Tipo Obrigatório
phone [object Object] Object Não
email fulano.tal@email.com.br String Não
verifiedEmail false String Sim
address [object Object] Object Não
account [object Object] Object Sim
fingerprintVariables String Não
document 45985782000101 String Sim
documentType CNPJ String Sim
name João Silva String Não
tradeName Marca Comercial Exemplo String Não
Phone
Nome Valor Tipo Obrigatório
countryCode 55 Integer Sim
areaCode 51 Integer Sim
number 999999999 Integer Sim
verified True Boolean Sim
Address
Nome Valor Tipo Obrigatório
zipCode 90660101 String Sim
street Rua Saudável 123 String Não
number 555 String Não
complement apto 123 String Não
district 90660101 String Não
city Rio de Janeiro String Não
state Rio de Janeiro String Não
country Brasil String Não

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.

HTTP/1.1 200 Ok
Content-Type: application/json; charset=utf-8
{
  "operationType": 1,
  "cashType": 1,
  "recipient": {
    "document": "47739506842",
    "documentType": "CPF",
    "email": "teste.souza@clear.sale",
    "phone": {
      "countryCode": 55,
      "areaCode": 51,
      "number": 981710000
    },
    "BankAccountData": {
            "bankNumber": 123,
            "agencyNumber": 3,
            "accountNumber": 4621,
            "accountLastNumber": 5,
            "accountType": 1
    },
    "zipCode": "90660130",
    "ipDevice": "192.168.18.8"
  },
  "sender": {
    "document": "04518345851",
    "documentType": "CPF",
    "email": "teste@clear.sale",
    "phone": {
      "countryCode": 55,
      "areaCode": 51,
      "number": 995756363
    },
    "BankAccountData": {
            "bankNumber": 123,
            "agencyNumber": 3,
            "accountNumber": 4621,
            "accountLastNumber": 5,
            "accountType": 1
     },
    "zipCode": "90660120",
    "ipDevice": "192.168.200.68",
  },
   "key": {
      "value": "47739506842",
      "type": "CPF",
      "creationDateKey": "2023-08-29T19:20:50.197Z",
      "creationDateAccount": "2023-08-29T19:20:50.197Z"
    },
  "currency": "BRL",
  "amount": 200,
  "referenceDate": "2023-10-01T09:00:00-03:00",
  "statistics": {
    "lastUpdated": "2023-08-29T19:20:50.197Z",
    "counters": [
      {
        "type": "Confirmed_Frauds",
        "by": "key",
        "d3": 3,
        "d30": 15,
        "m6": 30
      }
    ]
  }
}

Parâmetros

Nome Valor Tipo Obrigatório
cashType 1 Enum Sim
operationType 1 Enum Sim
recipient [object Object] String Sim
sender [object Object] String Sim
currency BRL String Não
amount 110.55 Number Não
referenceDate 2023-10-01T09:00:00-03:00 Datetime Sim
key [object Object] Object Opcional
statistics [object Object] Object Opcional
Recipient / Sender
Nome Valor Tipo Obrigatório
document 73417176026 String Sim
documentType CPF String Sim
email teste@teste.com String Não
phone [object Object] Object Não
bankAccountData [object Object] Object Não
zipCode 90660101 String Não
ipdevice 192.168.18.8 String Não
Key
Nome Valor Tipo Obrigatório
value 10770753000130 String Sim
type CNPJ String Sim
creationDateKey 2019-11-18T03:00:00+00:00 String Não
creationDateAccount 2019-11-18T03:00:00+00:00 String Não
Phone
Nome Valor Tipo Obrigatório
countryCode 55 Integer Sim
areaCode 51 Integer Sim
number 999999999 Integer Sim
BankAccountData
Nome Valor Tipo Obrigatório
bankNumber 123 Integer Sim
agencyNumber 4 Integer Sim
accountNumber 56789 Integer Sim
accountLastNumber 1 Integer Sim
accountType 1 Integer Sim
Statistics
Nome Valor Tipo Obrigatório
lastUpdated 2021-12-28T14:49:56.9115638+00:00 String Não
counters [Array] String Opcional
counters[0].FraudEventCounterDto.type CONFIRMED_FRAUDS String Sim
counters[0].FraudEventCounterDto.by KEY String Sim
counters[0].FraudEventCounterDto.d3 3 Integer Não
counters[0].FraudEventCounterDto.d30 4 Integer Não
counters[0].FraudEventCounterDto.m6 5 Integer Não
OperationType
Nome Valor Tipo Obrigatório
1 Pix
2 Ted
3 Recarga de Celular
CashType
Nome Valor Tipo Obrigatório
1 In
2 Out
AccountType
Nome Valor Tipo Obrigatório
1 CACC Conta Corrente
2 SLRY Conta Salário
3 SVGS Conta Poupança
4 TRAN Conta de Pagamento

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.

HTTP/1.1 200 Ok
Content-Type: application/json; charset=utf-8
{
    "id": "94f82ab97c194c3f85e8262df4d13b7f",
    "score": {
        "value": 773.749267578125,
        "date": "2024-07-03T17:12:38.6898434+00:00"
    },
    "comportamentalScore": 916.41015625
}

Retorno AntifraudScore

Nome Valor Tipo Obrigatório
Id 94f82ab97c194c3f85e8262df4d13b7f String Sim
Score [object Object] [object Object] Sim
ComportamentalScore 916.41015625 Number Sim
Score
Nome Valor Tipo Obrigatório
Value 773.749267578125 Number Sim
date 2024-07-03T17:12:38.6898434+00:00 Datetime Sim

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.

HTTP/1.1 200 Ok
Content-Type: application/json; charset=utf-8
{
  "operationType": 1,
  "cashType": 1,
  "recipient": {
    "document": "47739506842",
    "documentType": "CPF",
    "email": "teste.souza@clear.sale",
    "phone": {
      "countryCode": 55,
      "areaCode": 51,
      "number": 981710000
    },
    "BankAccountData": {
            "bankNumber": 123,
            "agencyNumber": 3,
            "accountNumber": 4621,
            "accountLastNumber": 5,
            "accountType": 1
    },
    "zipCode": "90660130",
    "ipDevice": "192.168.18.8"
  },
  "sender": {
    "document": "04518345851",
    "documentType": "CPF",
    "email": "teste@clear.sale",
    "phone": {
      "countryCode": 55,
      "areaCode": 51,
      "number": 995756363
    },
    "BankAccountData": {
            "bankNumber": 123,
            "agencyNumber": 3,
            "accountNumber": 4621,
            "accountLastNumber": 5,
            "accountType": 1
     },
    "zipCode": "90660120",
    "ipDevice": "192.168.200.68",
  },
   "key": {
      "value": "47739506842",
      "type": "CPF",
      "creationDateKey": "2023-08-29T19:20:50.197Z",
      "creationDateAccount": "2023-08-29T19:20:50.197Z"
    },
  "currency": "BRL",
  "amount": 200,
  "referenceDate": "2023-10-01T09:00:00-03:00",
  "statistics": {
    "lastUpdated": "2023-08-29T19:20:50.197Z",
    "counters": [
      {
        "type": "Confirmed_Frauds",
        "by": "key",
        "d3": 3,
        "d30": 15,
        "m6": 30
      }
    ]
  }
}

Parâmetros

Nome Valor Tipo Obrigatório
cashType 1 Enum Sim
operationType 1 Enum Sim
recipient [object Object] String Sim
sender [object Object] String Sim
currency BRL String Não
amount 110.55 Number Não
referenceDate 2023-10-01T09:00:00-03:00 Datetime Sim
key [object Object] Object Opcional
statistics [object Object] Object Opcional
Recipient / Sender
Nome Valor Tipo Obrigatório
document 73417176026 String Sim
documentType CPF String Sim
email teste@teste.com String Não
phone [object Object] Object Não
bankAccountData [object Object] Object Não
zipCode 90660101 String Não
ipdevice 192.168.18.8 String Não
Key
Nome Valor Tipo Obrigatório
value 10770753000130 String Sim
type CNPJ String Sim
creationDateKey 2019-11-18T03:00:00+00:00 String Não
creationDateAccount 2019-11-18T03:00:00+00:00 String Não
Phone
Nome Valor Tipo Obrigatório
countryCode 55 Integer Sim
areaCode 51 Integer Sim
number 999999999 Integer Sim
BankAccountData
Nome Valor Tipo Obrigatório
bankNumber 123 Integer Sim
agencyNumber 4 Integer Sim
accountNumber 56789 Integer Sim
accountLastNumber 1 Integer Sim
accountType 1 Integer Sim
Statistics
Nome Valor Tipo Obrigatório
lastUpdated 2021-12-28T14:49:56.9115638+00:00 String Não
counters [Array] String Opcional
counters[0].FraudEventCounterDto.type CONFIRMED_FRAUDS String Sim
counters[0].FraudEventCounterDto.by KEY String Sim
counters[0].FraudEventCounterDto.d3 3 Integer Não
counters[0].FraudEventCounterDto.d30 4 Integer Não
counters[0].FraudEventCounterDto.m6 5 Integer Não
OperationType
Nome Valor Tipo Obrigatório
1 Pix
2 Ted
3 Recarga de Celular
CashType
Nome Valor Tipo Obrigatório
1 In
2 Out
AccountType
Nome Valor Tipo Obrigatório
1 CACC Conta Corrente
2 SLRY Conta Salário
3 SVGS Conta Poupança
4 TRAN Conta de Pagamento

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).

HTTP/1.1 200 Ok
Content-Type: application/json; charset=utf-8
{
    "id": "4dc3c4dbe86f444e8931e8c30c498aea",
    "score": {
        "value": 862.3741455078125,
        "date": "2024-07-03T11:42:24.4173372-03:00"
    },
    "decidedRuleName": "Aprovar_pix_goodList",
    "finalDecision": "APA",
    "comportamentalScore": 892.904755175415
}

Retorno AntifraudDecision

Nome Valor Tipo Obrigatório
Id 4dc3c4dbe86f444e8931e8c30c498aea String Sim
Score [object Object] [object Object] Sim
DecidedRuleName Aprovar_pix_goodList String Sim
FinalDecision APA String Sim
ComportamentalScore 892.904755175415 Number Sim
Score
Nome Valor Tipo Obrigatório
Value 862.37414 Number Sim
date 2024-07-03T11:42:24.4173372-03:00 Datetime Sim