Introdução

Descrição do Produto

Segurança

Funcionalidades Disponíveis

Fluxo de Integração

Swagger

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.

Segue algumas dicas, referente ao token:

• O tempo de expiração será em minutos (1440 min).
• O cliente realizará o gerenciamento do ciclo de vida, com base no tempo de expiração.
• Somente gere um novo token após a expiração do seu token atual.

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
    }
    
    

FeedbackAntifraud - Post - Retroalimentação de marcações de fraude

Este endpoint está disponível na API na seguinte rota "v1/feedback/antifraud". Tem a finalidade de receber dados relacionados a um alerta de fraude sobre alguma informação do contexto da nossa solução.

HTTP/1.1 200 Ok
Content-Type: application/json; charset=utf-8
{
    "IdTransaction": "4dc3c4dbe86f444e8931e8c30c498aea",
    "IsFraud": true,
    "UserType" : "1"
    "Description": "Fraude de roubo de whatsapp relatada pelo cliente em XX/YY/ZZZZ",
    "DataFraud": "2021-07-20T17:19:22.7506499Z"
}

AntifraudScore - Post - Geração de Score sobre análise da transaçã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:

• 0 a 500 - Baixo risco
• 501 a 800 - Médio risco
• Acima de 800 - Alto risco

Regras gerais dos campos:

• OperationType = 4 (Boleto) não é permitido para esta rota.
• O campo document do objeto sender e recipient podem receber valores mascarados.
• O formato da máscara deve seguir o seguinte padrão:
• 3 asteriscos nos 3 primeiros números + 6 números + 2 asteriscos nos 2 últimos números.
• Exemplo: ***223640**
• Qualquer formato diferente deste, retornará uma mensagem de erro (status code = 400).
• Somente o CPF poderá ser mascarado. Não serão aceitos CNPJ´s mascarados.
• O CPF mascarado pode ser informado em ambos os objetos sender e recipient na mesma transação.
• Quando informado um CPF mascarado, o nome do pagador e recebedor são de preenchimento obrigatório, bem como o tipo de documento.
• O campo documentType deve ser igual a "CPF".
• Quando o cashType for IN representa uma transação de recebimento de um Pix, logo, o foco da análise dos dados, incluindo os dados bancários, será com base nos dados do recebedor deste Pix (recipient).
• Quando o cashType for OUT representa uma transação de pagamento de um Pix, logo, o foco da análise dos dados, incluindo os dados bancários, será com base nos dados do pagador deste Pix (sender).
• Os dados bancários do Recebedor(recipient) são de preenchimento obrigatório(existir no payload) somente em casos de CASHTYPE ser IN.
• Os dados bancários no Pagador(sender) são de preenchimento obrigatório(existir no payload) somente em casos de CASHTYPE ser OUT.

Conceitos importantes:

• Pagador - objeto sender
• Recebedor - objeto recipient
• IN - tipo de transação que foca no dados do Recebedor
• OUT - tipo de transação que foca nos dados do Pagador

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.

Retornos do score:

• Valor negativo do score - deve ser reportado, junto com os valores do CPF e/ou CNPJ e valor, para análise dos dados.
• Erro 500 - deve ser reportado, junto com os valores do CPF e/ou CNPJ e valor, para análise dos dados e da infraestrutura geral do sistema.

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"
        }
    }
    
    

Retornos da API:

• 201 - Sucesso
• 400 - Refere-se ao preenchimento incorreto dos campos
• 401 - Não autorizado, significa problemas de acesso
• 500 - Erro no servidor ou banco de dados

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"
    }
}

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.

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.

• 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.
• OperationType = 4 (Boleto) é opcional preencher recipient para esta rota.

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"
    }
    
    

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.417Z"
    },
    "decidedRuleName": "Aprovar_pix_goodList",
    "finalDecision": "APA"
}