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
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:
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.
Atenção: O Tempo de validade do Token gerado após a autenticação na API é de 24 Horas (ou 1440 minutos). Após esse período, um novo Token deverá ser gerado!
Abaixo seguem as funcionalidades disponíveis para utilização no Serviço Antifraude para Pagamentos Instantâneos:
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.
https://pixapi-h.clearsale.com.br
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.
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.
https://pixapi.clearsale.com.br
Possíveis problemas: erro ao autenticar a requisição. Consulte o valor do token.
Possíveis problemas: verifique se algum campo no corpo da requisição não está preenchido.
Possíveis problemas: algum tipo de problema está afetando o desempenho do servidor que você está tentando acessar.
Será possível visualizar as regras no swagger através deste link =>
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.
Segue algumas dicas, referente ao token:
Request:
HTTP/1.1 200 Ok
Content-Type: application/json; charset=utf-8
{
"USERNAME": "{{USERNAME_API_PIX}}",
"PASSWORD": "{{PASSWORD_API_PIX}}"
}
Response:
HTTP/1.1 200 Ok
Content-Type: application/json; charset=utf-8
{
"token": "eyJhbGciOiJ............CkoxKLwY1qvw0",
"expiresInMinutes": 1440
}
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
Username | usuario_automatico | String | Sim |
Password | senha12345 | String | Sim |
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.
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 | yyyy-MM-ddTHH:mm:ss.fffZ | String | Sim |
status | 2 | String | Sim |
relatedEntries | [object Object] | Object | Sim |
relatedTransfers | [object Object] | Object | Sim |
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 |
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 | yyyy-MM-ddTHH:mm:ss.fffZ | String | Sim |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
value | "00020101021126440014br.gov.bcb.pix0122fulano2019@example.com5204000053039865802BR5913FULANO DE TAL6008BRASILIA6304DFE3" | String | Sim |
dynamicUrl | [object Object] | Object | Não |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
url | http://bx.com.br/spi/U0VHUkVET1RPVEFMTUVOVEVBTEVBVE9SSU8= | String | Sim |
ip | 127.0.0.1 | String | Sim |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
url | http://bx.com.br/spi/U0VHUkVET1RPVEFMTUVOVEVBTEVBVE9SSU8= | String | Sim |
ip | 127.0.0.1 | String | Sim |
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 |
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 | yyyy-MM-ddTHH:mm:ss.fffZ | String | Sim |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
lastUpdated | yyyy-MM-ddTHH:mm:ss.fffZ | 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 |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
value | 10770753000130 | String | Sim |
type | CNPJ | String | Sim |
creationDate | yyyy-MM-ddTHH:mm:ss.fffZ | String | Não |
keyOwnershipDate | yyyy-MM-ddTHH:mm:ss.fffZ | String | Não |
openClaimCreationDate | yyyy-MM-ddTHH:mm:ss.fffZ | String | Não |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
phone | [object Object] | Object | Não |
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 |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
countryCode | 55 | Integer | Sim |
areaCode | 51 | Integer | Sim |
number | 999999999 | Integer | Sim |
verified | True | Boolean | Sim |
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 |
A API PIX possui a seguinte rota para o endpoint do Antifraude Score: "v1/analysis/antifraudscore". Esta API tem como objetivo analisar os dados do pagador e recebedor, juntamente com o valor da transação, onde o pagador e recebedor podem ser pessoa física e/ou jurídica. O resultado da transação será o valor do score de risco de 0 a 1000, no qual, quanto maior o valor, maior será o risco de fraude e o mesmo vale inversamente.
Os valores de referência do score são:
Conceitos importantes:
OBS: Campos com obrigatoriedade "opcional", ou seja, podem ou não ser preenchidos, mas se preenchido o objeto pai, todos os campos deste objeto serão de preenchimento obrigatório, pois dependem do objeto pai. O exemplo de retorno está no AntifraudScore - Get.
Request:
HTTP/1.1 200 Ok
Content-Type: application/json; charset=utf-8
{
"operationType": 1,
"cashType": 1,
"recipient": {
"document": "68227956009",
"documentType": "CPF",
"name": "João Isaac Breno Melo",
"email": "joao_melo@cognis.com",
"phone": {
"countryCode": 55,
"areaCode": 51,
"number": 984709799
},
"BankAccountData": {
"bankNumber": "123",
"agencyNumber": "4",
"accountNumber": "190827",
"accountLastNumber": "5",
"accountType": 1
},
"zipCode": "90660130",
"ipDevice": "192.168.18.8"
},
"sender": {
"document": "40086260006",
"documentType": "CPF",
"name": "Heloisa Márcia Alice Barbosa",
"email": "heloisamarciabarbosa@securitycontrol.com.br",
"phone": {
"countryCode": 55,
"areaCode": 51,
"number": 986133197
},
"BankAccountData": {
"bankNumber": "456",
"agencyNumber": "7",
"accountNumber": "968627",
"accountLastNumber": "5",
"accountType": 1
},
"zipCode": "90660120",
"ipDevice": "192.168.200.68",
},
"registeredDevice" : true,
"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.000Z",
"statistics": {
"lastUpdated": "2023-08-29T19:20:50.197Z",
"counters": [
{
"type": "Confirmed_Frauds",
"by": "key",
"d3": 3,
"d30": 15,
"m6": 30
}
]
},
"params": {
"models": {
"name": "ModeloPadrao",
"environment": "DEV"
},
"trees": {
"name": "",
"environment": ""
}
}
}
Response:
HTTP/1.1 200 Ok
Content-Type: application/json; charset=utf-8
{
"id": "ab9b34e6f4s5aa8w4f5gdf0fb068",
"score": {
"value": 555.0621337890625,
"date": "2024-11-12T13:31:12.5386709+00:00"
}
}
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
cashType | 1 | 2 | Enum | Sim |
operationType | 1 | 2 | 3 | Enum | Sim |
recipient | [object Object] | String | Sim |
sender | [object Object] | String | Sim |
currency | BRL | String | Não |
amount | 110.55 | Number | Sim |
registeredDevice | true | Bool | Não |
referenceDate | yyyy-MM-ddTHH:mm:ss.fffZ | Datetime | Sim |
key | [object Object] | Object | Opcional |
statistics | [object Object] | Object | Opcional |
params | [object Object] | Object | Opcional |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
document | 73417176026 ou ***171760** | String | Sim |
documentType | CPF | String | Sim |
name | Claudio da Silva Souza | String | Não (Obrigatório caso document possua máscara) |
teste@teste.com | String | Não | |
phone | [object Object] | Object | Opcional |
bankAccountData | [object Object] | Object | Sim |
zipCode | 90660101 | String | Não |
ipdevice | 192.168.18.8 | String | Não |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
value | 10770753000130 | String | Sim |
type | CNPJ | String | Sim |
creationDateKey | yyyy-MM-ddTHH:mm:ss.fffZ | String | Não |
creationDateAccount | yyyy-MM-ddTHH:mm:ss.fffZ | String | Não |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
countryCode | 55 | Integer | Sim |
areaCode | 51 | Integer | Sim |
number | 999999999 | Integer | Sim |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
bankNumber | 123 | String | Sim |
agencyNumber | 4 | String | Sim |
accountNumber | 56789 | String | Sim |
accountLastNumber | 1 | String | Sim |
accountType | 1 | Integer | Sim |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
lastUpdated | yyyy-MM-ddTHH:mm:ss.fffZ | String | Não |
counters | [Array] | String | Opcional |
counters[0].FraudEventCounterDto.type | CONFIRMED_FRAUDS | String | Não |
counters[0].FraudEventCounterDto.by | KEY | String | Não |
counters[0].FraudEventCounterDto.d3 | 3 | Integer | Não |
counters[0].FraudEventCounterDto.d30 | 4 | Integer | Não |
counters[0].FraudEventCounterDto.m6 | 5 | Integer | Não |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
1 | Pix | Integer | |
2 | Ted | Integer | |
3 | Recarga de Celular | Integer | |
4 | Boleto - Somente para rota AntifraudDecision | Integer |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
1 | In | Integer | |
2 | Out | Integer |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
1 | CACC | Conta Corrente | |
2 | SLRY | Conta Salário | |
3 | SVGS | Conta Poupança | |
4 | TRAN | Conta de Pagamento |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
models | [object Object] | Objeto | Não |
trees | [object Object] | Objeto | Não |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
name | ModeloPadrao | String | Não |
environment | PRD | String | Não |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
name | ModeloPadrao | String | Não |
environment | PRD | String | Não |
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"
}
}
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
Id | 94f82ab97c194c3f85e8262df4d13b7f | String | Sim |
Score | [object Object] | [object Object] | Sim |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
Value | 773.749267578125 | Number | Sim |
date | yyyy-MM-ddTHH:mm:ss.fffZ | Datetime | Sim |
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.
O sistema retorna além do score a informação de APA (aprova) /RPA (reprova), o nome da regra que aprovou ou reprovou a transação.
Obs:Request:
HTTP/1.1 200 Ok
Content-Type: application/json; charset=utf-8
{
"operationType": 1,
"cashType": 1,
"recipient": {
"document": "47739506842",
"documentType": "CPF",
"name": "Teste da Silva Souza",
"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",
"name": "Silva Pereira Souza",
"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",
},
"registeredDevice" : true,
"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.000Z",
"statistics": {
"lastUpdated": "2023-08-29T19:20:50.197Z",
"counters": [
{
"type": "Confirmed_Frauds",
"by": "key",
"d3": 3,
"d30": 15,
"m6": 30
}
]
},
"params": {
"models": {
"name": "ModeloPadrao",
"environment": "DEV"
},
"trees": {
"name": "",
"environment": ""
}
}
}
Response:
HTTP/1.1 200 Ok
Content-Type: application/json; charset=utf-8
{
"id": "80bb72544sds5484ff5gdffe398",
"score": {
"value": 706.5914916992188,
"date": "2024-11-12T13:29:24.7865885+00:00"
},
"decidedRuleName": "pix-fluxo-de-decisao-r6-recebedor",
"finalDecision": "RPA"
}
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
cashType | 1 | 2 | Enum | Sim |
operationType | 1 | 2 | 3 | Enum | Sim |
recipient | [object Object] | String | Sim |
sender | [object Object] | String | Sim |
currency | BRL | String | Não |
amount | 110.55 | Number | Sim |
registeredDevice | true | Bool | Não |
referenceDate | yyyy-MM-ddTHH:mm:ss.fffZ | Datetime | Sim |
key | [object Object] | Object | Opcional |
statistics | [object Object] | Object | Opcional |
params | [object Object] | Object | Opcional |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
document | 73417176026 ou ***171760** | String | Sim |
documentType | CPF | String | Sim |
name | Claudio da Silva Souza | String | Não (Obrigatório caso document possua máscara) |
teste@teste.com | String | Não | |
phone | [object Object] | Object | Opcional |
bankAccountData | [object Object] | Object | Sim |
zipCode | 90660101 | String | Não |
ipdevice | 192.168.18.8 | String | Não |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
value | 10770753000130 | String | Sim |
type | CNPJ | String | Sim |
creationDateKey | yyyy-MM-ddTHH:mm:ss.fffZ | String | Não |
creationDateAccount | yyyy-MM-ddTHH:mm:ss.fffZ | String | Não |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
countryCode | 55 | Integer | Sim |
areaCode | 51 | Integer | Sim |
number | 999999999 | Integer | Sim |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
bankNumber | 123 | String | Sim |
agencyNumber | 4 | String | Sim |
accountNumber | 56789 | String | Sim |
accountLastNumber | 1 | String | Sim |
accountType | 1 | Integer | Sim |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
lastUpdated | yyyy-MM-ddTHH:mm:ss.fffZ | String | Não |
counters | [Array] | String | Opcional |
counters[0].FraudEventCounterDto.type | CONFIRMED_FRAUDS | String | Não |
counters[0].FraudEventCounterDto.by | KEY | String | Não |
counters[0].FraudEventCounterDto.d3 | 3 | Integer | Não |
counters[0].FraudEventCounterDto.d30 | 4 | Integer | Não |
counters[0].FraudEventCounterDto.m6 | 5 | Integer | Não |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
1 | Pix | Integer | |
2 | Ted | Integer | |
3 | Recarga de Celular | Integer | |
4 | Boleto - Somente para rota AntifraudDecision | Integer |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
1 | In | Integer | |
2 | Out | Integer |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
1 | CACC | Conta Corrente | |
2 | SLRY | Conta Salário | |
3 | SVGS | Conta Poupança | |
4 | TRAN | Conta de Pagamento |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
models | [object Object] | Objeto | Não |
trees | [object Object] | Objeto | Não |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
name | ModeloPadrao | String | Não |
environment | PRD | String | Não |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
name | ModeloPadrao | String | Não |
environment | PRD | String | Não |
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.417Z"
},
"decidedRuleName": "Aprovar_pix_goodList",
"finalDecision": "APA"
}
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 |
Nome | Valor | Tipo | Obrigatório |
---|---|---|---|
Value | 862.37414 | Number | Sim |
date | yyyy-MM-ddTHH:mm:ss.fffZ | Datetime | Sim |