Manual de Integração - Velocity

Redirecionando para https://docs.cielo.com.br/risco/docs/velocity ...

As documentações do Velocity estão em um novo portal

Acesse o novo portal de desenvolvedores E-commerce docs.cielo.com.br.

Atenção: O conteúdo desta página está sendo descontinuado e não receberá atualizações a partir de 14/08/2024. Visite a nova documentação em docs.cielo.br.

Visão Geral

Para estabelecimentos comerciais que atuam no mercado de comércio eletrônico e eventualmente recebem transações fraudulentas, o Velocity é um produto que identificará os comportamentos suspeitos de fraude. O Velocity é um aliado na avaliação de comportamentos suspeitos de compra, pois os cálculos serão baseados em variáveis.

A API é baseada em arquitetura REST, que trocam dados em formato JSON seguindo fluxos de autorização definidos pelo protocolo OAuth 2, onde todos os padrões são amplamente utilizados pelo mercado e suportado pelas comunidades técnicas.

Para saber mais sobre OAuth 2, consulte https://oauth.net/2/

Objetivo

Velocity

• Auxilia na detecção de suspeitas de fraude;
• Aliado para bloquear ataques em rajada (testes de cartão, por exemplo), bem como avaliações de comportamentos suspeitos de compra;
• Tem cálculos baseados em análise de velocidade de variáveis e a incidência destas em determinados intervalos de tempo.

Documentação

O objetivo desta documentação é orientar sobre como integrar com a API Velocity Braspag, descrevendo as operações disponíveis com exemplos de requisições e respostas.

Para executar uma operação, combine o endpoint base do ambiente com o endpoint da operação desejada e envie utilizando o VERBO HTTP conforme descrito na operação.

Funcionamento

Análise de regras

O Velocity realiza análises em cima de regras habilitadas para os tipos de variáveis abaixo:

Confira mais informações sobre Como gerenciar as regras do Velocity Check

A análise ocorre em cima de cada variável (V), contando quantas vezes (H) a mesma passou na Braspag para a sua loja dentro de um determinado período (P).

• V = Variável
• H = Hits (Quantidade)
• P = Período

Com estes 3 elementos, teríamos a seguinte regra, Máximo de 5 Hits de Número do Cartão em 12 Hora(s), onde:

• V = Número do cartão de crédito
• H = 5
• P = 12 Horas

Com isso, o Velocity ao receber a 6ª transação com o mesmo número de cartão (V) das outras 5 anteriores, a regra acima ao ser executada e detectar que a quantidade (H) excedeu as 5 permitidas no período (P) entre a data da primeira transação e a data da 6ª recebida, esta terá o status de rejeitada, o número do cartão poderá ir quarentena e a resposta terá o conteúdo de que a transação foi rejeitada devido a regra.

Quarentena

Ao cadastrar uma regra é possível especificar quanto tempo o valor de uma determinada variável irá ser levado em consideração nas próximas análises, ou seja, se o cliente quiser identificar a quantidade de vezes que o mesmo número de cartão se repetiu para um período de 12 horas dentro de um intervalo de 2 dias, não será necessário o Velocity realizar esta contagem retroativa agrupando por período. Neste cenário por exemplo, a aplicação teria que realizar a contagem para os seguintes intervalos:

• D-2 = 0h as 12h
• D-2 = 12h as 0h
• D-1 = 0h as 12h
• D-1 = 12h as 0h

Com a quarentena configurada, a aplicação não irá realizar essa contagem retroativa por período, pois na análise é verificado se existe o valor da variável número de cartão em quarentena. Por exemplo: para a regra mostrada acima (Máximo de 5 Hits de Número do Cartão em 12 Hora(s)), o tempo de expiração se definido em 2 dias, a regra será analisada apenas para o período configurado, ou seja, 12 horas para trás e irá verificar durante 2 dias para trás se número do cartão se encontra em quarentena.

Uma transação analisada, não rejeitada pela regra, mas rejeitada pela quarentena, terá o retorno informando que foi rejeitada pela quarentena.

Lista Negativa

Uma transação a ser analisada, e o número do cartão enviado para análise estiver na lista negativa, a transação será rejeitada, independente de existir regra cadastrada para este tipo de variável ou não e as demais regras para outros tipos de variáveis serão ignoradas.

Uma transação analisada e rejeitada pela lista negativa terá o retorno informando que foi rejeitada pela lista negativa.

Lista Positiva

Uma transação a ser analisada, e o número do cartão enviado para análise estiver na lista positiva, a transação será aceita, independente de existir regra cadastrada para este tipo de variável ou não e as demais regras para outros tipos de variáveis serão ignoradas.

Uma transação analisada e aceita pela lista positiva terá o retorno informando que foi aceita pela lista positiva.

Hosts

API BraspagAuth

API Velocity Braspag

Autenticação

Tokens de Acesso

A API Velocity Braspag utiliza o protocolo padrão de mercado OAuth 2.0 para autorização de acesso a seus recursos específicos por ambientes, que são: Sandbox e Produção.

Esta sessão descreve o fluxo necessário para que aplicações cliente obtenham tokens de acesso válidos para uso na API.

Obtenção do token de acesso

O token de acesso é obtido através do fluxo oauth client_credentials. O diagrama abaixo, ilustra, em ordem cronológica, a comunicação que se dá entre a Aplicação Cliente, a API BraspagAuth e a API Velocity Braspag.

1. A Aplicação Cliente, informa à API BraspagAuth sua credencial.

2. O BraspagAuth valida a credencial recebida. Se for válida, retorna o token de acesso para a Aplicação Cliente.

3. A Aplicação Cliente informa o token de acesso no cabeçalho das requisições HTTP feitas à API Velocity Braspag.

4. Se o token de acesso for válido, a requisição é processada e os dados são retornados para a Aplicação Cliente.

Solicite uma credencial abrindo um ticket através da nossa ferramenta de suporte, enviando o(s) IP(s) de saída dos seus servidores de homologação e produção.
Suporte Braspag

Como obter o token

Uma vez em posse da credencial, será necessário “codificá-la” em Base64, utilizando a convenção client_id:client_secret, e enviar o resultado no cabeçalho através do campo Authorization.

Exemplo:

• client_id: braspagtestes
• client_secret: 1q2w3e4r5t6y7u8i9o0p0q9w8e7r6t5y4u3i2o1p
• String a ser codificada em Base64: braspagtestes:1q2w3e4r5t6y7u8i9o0p0q9w8e7r6t5y4u3i2o1p
• Resultado após a codificação: YnJhc3BhZ3Rlc3RlczoxcTJ3M2U0cg==

Request

Parâmetros no cabeçalho (Header)

Parâmetros no corpo (Body)

Response

{
  "access_token": "faSYkjfiod8ddJxFTU3vti_ ... _xD0i0jqcw",
  "token_type": "bearer",
  "expires_in": 599
}

Parâmetros no corpo (Body)

Analisando uma transação

A Braspag, ao receber os dados do pedido, irá analisá-lo de acordo com o descrito no tópico Funcionamento.

Importante

• Os campos são opcionais e as regras serão disparadas somente se o valor no campo correspondente a regra for enviado, ou seja, se existir uma regra relacionada ao campo documento do comprador e o campo Customer.Identity não for enviado, esta regra não será disparada na análise.

• Os valores dos campos devem ser enviados sempre no mesmo formato, por exemplo: CEP do endereço de cobrança ou entrega, enviar SEMPRE uma das opções entre valor com formatação (xxxxx-xxx) e sem formatação (xxxxxxxx).

Requisição

{
  "Transaction": {
    "OrderId": "123456789AB",
    "Date": "2018-02-02 13:51:56.854",
    "Amount": 96385
  },
  "Card": {
    "Holder": "Joao C Silva",
    "Number": "4444555566667777",
    "Expiration": "12/2023",
    "Brand": "visa"
  },
  "Customer": {
    "Name": "Joao Couves da Silva",
    "Identity": "12345678910",
    "IpAddress": "127.0.0.1",
    "BirthDate": "1983-10-01",
    "Email": "joaocouvessilva@email.com",
    "Phones": [ 
    {
      "Type": "Phone",
      "DDI": "55",
      "DDD": "21",
      "Number": "21114700",
      "Extension": "4720"
    },
    {
      "Type": "Workphone",
      "DDI": "55",
      "DDD": "21",
      "Number": "25899600",
      "Extension": "9612" 
    },
    {
      "Type": "Cellphone",
      "DDI": "55",
      "DDD": "21",
      "Number": "987654321"
    }
    ],
    "Billing": {
      "Street": "Rua do Escorrega",
      "Number": "171",
      "Complement": "Casa 71",
      "Neighborhood": "Piratininga",
      "City": "Niterói",
      "State": "RJ",
      "ZipCode": "24355-350",
      "Country": "BR"
    },
    "Shipping": {
      "Street": "Rua do Equilibra",
      "Number": "171",
      "Complement": "Casa 2",
      "Neighborhood": "Centro",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "ZipCode": "24355-351",
      "Country": "BR"
    }
  }
}

Parâmetros no cabeçalho (Header)

Parâmetros no corpo (Body)

Resposta

{
    "AnalysisResult": {
        "Score": 100,
        "Status": "Reject",
        "AcceptByWhiteList": false,
        "RejectByBlackList": false
    },
    "Links": [
        {
            "Method": "GET",
            "Rel": "self",
            "Href": "https://velocitysandbox.braspag.com.br/Analysis/v2/80832037-97b4-4952-8ae7-c37be13cce7a"
        }
    ],
    "Transaction": {
        "Id": "b88a8b60-9e7d-4064-8413-059e0a896aef",
        "Date": "2018-02-02T13:51:56.854"
    }
}

Parâmetros no cabeçalho (Header)

Parâmetros no corpo (Body)

Tabelas

Tabela 1 - Customer.Identity

Tabela 2 - Customer.Phones[n].Type

Tabela 3 - AnalysisResult.Status