Introdução

Seja bem-vindo ao SafeGuard! Nesta documentação, falamos sobre nossa análise antifraude e detalhamos as APIs que disponibilizamos para realizar a avaliação das suas vendas.

Para alcançar resultados mais efetivos, nosso serviço realiza dois tipos de análise: a dos dados da venda e a do comportamento do usuário no e-commerce.

Assim que uma pessoa acessa a sua página, já iniciamos o monitoramento de suas ações, através de nossa API em Javascript. Quando ela confirma a compra, recebemos todos os detalhes do pedido através de nossa API REST e avaliamos o risco dessa venda.

A seguir, explicamos com maior profundidade os procedimentos de configuração e integração com nossas APIs.

Em casos de dúvidas, é só entrar em contato conosco através de nosso e-mail ou através de um ticket de suporte para que possamos ajudá-lo da melhor maneira.

Monitoramento

Identificação do cliente

O primeiro passo na avaliação de um indivíduo é identificá-lo. Nós fazemos isso criando um fingerprint dos seus usuários através da inclusão de uma API Javascript na sua plataforma.

Passo 1. Na sua página, inclua o script do SafeGuard

<head>
    ...
    <!-- SafeGuard Javascript -->
    <script src='https://www.safeguard.vc/assets/safeguard_api_v3.js'></script>
    <!-- SafeGuard Javascript -->
    ...
</head>

Após incluir o script no seu e-commerce, basta iniciar a API do SafeGuard para recuperar o token de transação do seu cliente.

Esse token deve ser enviado para o seu servidor para que possa ser enviado junto com os dados da compra.

Passo 2. Inicialize a API do SafeGuard

var safeGuard = new app.SafeGuard();
safeGuard.init({
  identification: USER_IDENTIFICATION,
  identificationType: USER_IDENTIFICATION_TYPE,
  authorizationKey: YOUR_APPLICATION_PUBLIC_KEY,
  onSuccess: function(data) {
    /*
      At this point, the API was successfully started.

      So you should send the generated transaction token to your server.

      The results are available on data object, eg:
      {
        transactionToken: 'a-transaction-token',
        needsTokenPasswordToIssue: true
      }
    */
  },
  onError: function(status, message) {
    /*
      Check the status and message to understand the issue
    */
  }
});

Substitua YOUR_APPLICATION_PUBLIC_KEY com a chave pública fornecida pelo SafeGuard para sua conta.

Substitua USER_IDENTIFICATION com a identificação do usuário (email, id ou username).

Substitua USER_IDENTIFICATION_TYPE com o tipo de identificação do usuário (email, cpf ou username).

Antifraude

Analisamos o risco de uma venda assim que o cliente confirma a compra na sua plataforma. Através de nossos algoritmos e de nossa tecnologia machine learning, avaliaremos todos os detalhes da venda (comprador, itens comprados, meio de pagamento, endereços...), juntamente com os dados do comportamento do usuário.

Para isso, recebemos os dados através de um POST na nossa API REST de análise antifraude. No envio dos dados, você precisará configurar um HEADER de autenticação e construir o corpo da análise com as informações da venda no formato esperado pela nossa API (vide explicações abaixo).

Autenticação da API

O SafeGuard espera um header HTTP chamado de Authorization que possui os seguintes dados:

userIdentification: A identificação do usuário gerada pelo Javascript;
transactionToken: O token de transação gerado pelo Javascript;
privateKey: A chave de aplicação privada que deve ser armazenada no seu servidor;

# O Header segue este seguinte formato:

Authorization: "SAFEGUARD privateKey~transactionToken:userIdentification"

# No caso, por exemplo, em que:

# - privateKey: a51b4f34
# - transactionToken: 18cebab0
# - userIdentification: usuario123

# O Header deve ser enviado da seguinte maneira:

Authorization: "SAFEGUARD a51b4f34~18cebab0:usuario123"

Envio dos dados

A chamada para o SafeGuard deve ser feita atráves de um HTTP POST, com um JSON o formato pré-definido no corpo da requisição.

HTTP Request

POST https://www.safeguard.vc/api/risk/v3/risk_analysis

HTTP Body

O corpo da mensagem que deve ser enviado ao SafeGuard segue o seguinte formato:

[
  {
    "additional_parameters": [],
    "currency": "BRL",
    "destination": "GIG",
    "identifier": "LOC123",
    "issuing_company": {},
    "origin": "GRU",
    "source": "Sabre",
    "channel": "web",
    "tickets_to_issue": [],
    "travel_type": "oneway"
  }
]

Campo	Descrição	Obrigatório
`additional_parameters`	Lista de objetos com os parâmetros adicionais	Não
`currency`	Moeda utilizada no pagamento	Sim
`destination`	IATA do aeroporto de destino	Sim
`identifier`	Localizador	Sim
`issuing_company`	Objeto com os dados da agência	Sim
`origin`	IATA do aeroporto de origem	Sim
`source`	Origem da venda	Sim
`tickets_to_issue`	Lista de objetos com os dados dos tickets	Sim
`travel_type`	Tipo da viagem (oneway/roundtrip)	Sim
`channel`	Canal da venda	Não

Dados da Agência

{
  "address": {
    "country": "BRA",
    "postal_code": "00000000",
    "state": "SP",
    "street": "Rua do Arouche, 23",
    "city": "sao paulo"
  },
  "company_identification": "12551558000144",
  "credit_limit": 300000000,
  "external_id": "AGCNY123456",
  "name": "Agencia XY"
}

Campo	Descrição	Exemplo
`address`*	Objeto com os dados de endereço	{}
`company_identification`*	CNPJ ou documento da agência	12551558000144
`credit_limit`	Valor do limite de crédito em centavos	300000000
`external_id`*	Identificador da agência	AGCNY123456
`name`*	Nome da agência	Agencia XY

Os campos obrigatórios estão marcados com *

Dados de Endereço da Agência

{
  "country": "BRA",
  "postal_code": "02345009",
  "state": "SP",
  "street": "Rua do Arouche, 26",
  "city": "sao paulo"
}

Campo	Descrição	Exemplo
`country`*	País em ISO 3166	"BRA"
`postal_code`*	CEP	"02345009"
`state`*	Estado/região	"SP"
`street`*	Endereço	"Rua do Arouche, 23"
`city`*	Cidade	"sao paulo"

Os campos obrigatórios estão marcados com *

Dados dos Tickets

{
  "air_company": "JJ",
  "class": "$",
  "first_name": "Fulano",
  "flight_groups": [],
  "last_name": "Tal",
  "passenger_type": "adult",
  "payments": [],
  "price": 15000,
  "status": "issued"
}

Campo	Descrição	Exemplo
`air_company`*	Código da companhia aérea	"JJ"
`class`*	Classe do Voo	"$"
`first_name`*	Primeiro nome do passageiro	"Fulano"
`flight_groups`*	Lista de objetos com os dados dos trechos	[]
`last_name`*	Último nome do passageiro	"Tal"
`passenger_type`*	Tipo de passageiro (adult/child/infant)	"adult"
`payments`*	Lista de objetos com os dados dos pagamentos	[]
`price`*	Preço da passagem em centavos	"15000"
`status`*	Indicador da venda da passagem (issued/not_issued)	"issued"

Os campos obrigatórios estão marcados com *

Dados dos Trechos

[
  {
    "air_company_operator": "JJ",
    "arrival_at": "2015-09-17T19:00:00-03:00",
    "cabin": "economic",
    "departure_at": "2015-09-17T18:00:00-03:00",
    "destination": "GIG",
    "origin": "GRU"
  }
]

Campo	Descrição	Exemplo
`air_company_operator`*	Código da companhia aérea	"JJ"
`arrival_at`*	Data/Hora do chegada em ISO 8601	"2015-09-17T19:00:00-03:00"
`cabin`*	Tipo da passagem (economic/executive/first_class)	"economic"
`departure_at`*	Data/Hora do embarque em ISO 8601	"2015-09-17T18:00:00-03:00"
`destination`*	IATA do aeroporto de destino	Sim
`origin`*	IATA do aeroporto de origem	Sim

Os campos obrigatórios estão marcados com *

Dados de Pagamento

[
  {
    "credit_card_info": {
      "brand": "VISA",
      "holder_name": "FULANO DA SILVA",
      "number": "5555666677778888"
    },
    "type": "credit_card"
  },
  {
    "payment_description": "Faturado",
    "type": "other"
  }
]

Campo	Descrição	Exemplo
`type`*	Tipo de pagamento (credit_card, other)	"other"
`payment_description`*	Descrição do pagamento	"Faturado"
`credit_card_info.number`	Número do cartão de crédito (obrigatório quando para `credit_card`)	"5555666677778888"
`credit_card_info.holder_name`	Nome do titular do cartão de crédito (obrigatório quando para `credit_card`)	"FULANO DA SILVA"
`credit_card_info.brand`	Bandeira do cartão de crédito (obrigatório quando para `credit_card`)	"VISA"

Os campos obrigatórios estão marcados com *

Retorno da API

HTTP Status 200 - OK

Em caso de 200, a análise de risco retorna um JSON estruturado da seguinte forma:

[
  {
    "identifier": "UUKYRQ",
    "level": "ACCEPT",
    "score": 2
  }
]

Quando o HTTP status do retorno da análise de risco for igual à 200, significa que tudo ocorreu como esperado e a análise foi feita com sucesso.

Nesse caso, é retornado um JSON com as seguintes informações:

identifier: O localizador enviado no corpo da análise
score: A nota de risco da venda (varia de 0 à 100) sendo que quanto mais elevado, maior o risco da venda.
level: A ação que deve ser tomada na análise (ACCEPT, ANALYZE ou REFUSE) - essas ações são totalmente customizáveis no SafeGuard

HTTP Status 401 - Unauthorized

Quando o HTTP status do retorno da análise de risco for igual à 401, significa que o Header de autenticação estava inválido.

Nesse caso, o JSON da resposta será vazio.

HTTP Status 422 - Unprocessable Entity

Em caso de 422, a análise de risco retorna um JSON estruturado da seguinte forma:

{
  "currency": "missing",
  "issuing_company.credit_limit": "invalid_format"
}

Quando o HTTP status do retorno da análise de risco for igual à 422, significa que algum dado enviado para a análise não está no formato esperado pela API.

Nesse caso, o JSON da resposta contém uma lista de falhas que seguem a seguinte estrutura:

Demais HTTP Status Codes

Os demais status codes não são erros esperados pela API, e devem ser comunicados pelo nosso canal de suporte para maiores investigações e esclarecimentos.

Autenticação via Token

Capturar o código OTP do usuário

Após configurar e inicializar a API Javascript, você pode chamar a captura do código OTP em diversos momentos da sua aplicação executando o código descrito abaixo.

safeGuard.buildForm(
  function(data) {
    /*
        - here in 'data' you will receive the following:
          otp: user typed token code;
          transactionToken: token generated on the API initialization;

          - send both to your server with the user identification as well
    */
  }
);

Validação do código OTP

No seu servidor, valide a autenticidade do código digitado pelo usuário fazendo a seguinte chamada para nossa API.

Na validação, tanto o Header e Body da requisição, devem ser preenchidos com os dados recebidos no seu servidor.

Uma vez autenticado com sucesso, prossiga com a venda, caso contrário, reinicie o processo para pedir novamente que o usuário digite o token.

Informações Adicionais

Um transactionToken pode ser utilizado em apenas uma autenticação de token;
O transactionToken é expirado após 30 minutos do momento de sua criação e não é possível mais realizar autenticações com ele, sendo necessário recriá-lo via nossa API Javascript;

Autenticação da API

Nessa chamada, assim como na chamada de análise da venda, o SafeGuard espera um header HTTP chamado de Authorization que possui os seguintes dados:

userIdentification: A identificação do usuário gerada pelo Javascript;
transactionToken: O token de transação gerado pelo Javascript;
privateKey: A chave de aplicação privada que deve ser armazenada no seu servidor;


# O Header segue este seguinte formato:

Authorization: "SAFEGUARD privateKey~transactionToken:userIdentification"

# No caso, por exemplo, em que:

# - privateKey: a51b4f34
# - transactionToken: 18cebab0
# - userIdentification: usuario123

# O Header deve ser enviado da seguinte maneira:

Authorization: "SAFEGUARD a51b4f34~18cebab0:usuario123"

Envio dos dados

A chamada para o SafeGuard deve ser feita atráves de um HTTP POST, com um JSON o formato pré-definido no corpo da requisição.

HTTP Request

POST https://www.safeguard.vc/api/risk/v3/validate_otp

HTTP Body

O corpo da mensagem que deve ser enviado ao SafeGuard segue o seguinte formato:

{
  "authentication_token_number": "123456"
}

Retorno da API

HTTP Status 200 - OK

A autenticação foi validada com sucesso pelo SafeGuard

HTTP Status 401 - Unauthorized

Significa que o Header de autenticação estava inválido.

HTTP Status 422 - Unprocessable Entity

O usuário digitou o token de maneira incorreta ou o token de transação está inválido

Demais HTTP Status Codes

Os demais status codes não são erros esperados pela API, e devem ser comunicados pelo nosso canal de suporte para maiores investigações e esclarecimentos.

Consulta de BIN

Fornecemos informações referentes ao BIN do cartão de crédito para que você realize verificações sobre a consistência dos dados apresentados no momento da venda.

No envio dos dados, você precisará configurar um HEADER de autenticação e construir o corpo da análise com o número do BIN no formato esperado pela nossa API (vide explicações abaixo).

Autenticação da API

O SafeGuard espera um header HTTP chamado de Authorization da seguinte forma:

privateKey: A chave de aplicação privada que deve ser armazenada no seu servidor;


# O Header segue este seguinte formato:

Authorization: "privateKey"

# No caso, por exemplo, em que:

# - privateKey: a51b4f34

# O Header deve ser enviado da seguinte maneira:

Authorization: "a51b4f34"

Envio dos dados

A chamada para o SafeGuard deve ser feita atráves de um HTTP POST, com um JSON o formato pré-definido no corpo da requisição.

HTTP Request

POST https://www.safeguard.vc/api/risk/v3/bin_search

HTTP Body

O corpo da mensagem que deve ser enviado ao SafeGuard segue o seguinte formato:

{
  "number": "445566"
}

Quando o HTTP status do retorno da análise de risco for igual à 200, significa que tudo ocorreu como esperado e a análise foi feita com sucesso.

Nesse caso, é retornado um JSON com as seguintes informações:

bank_name: O banco emissor do cartão de crédito (NU PAGAMENTOS SA, BRADESCO, ITAU...)
brand_name: A bandeira do cartão de crédito (VISA, MASTERCARD, ELOCARD...)
level_name: O nível do cartão de crédito (STANDARD, GOLD, BUSINESS, CORPORATE...)
type_name: O tipo do cartão (CREDIT, DEBIT, PRE-PAID...)
country_name: O país em que o cartão foi emitido (BRAZIL, UNITED STATES, MEXICO...)
info: Qualque informação adicional registrada junto ao BIN

{
  "bank_name": "NU PAGAMENTOS SA",
  "brand_name": "MASTERCARD",
  "level_name": "PLATINUM",
  "type_name": "CREDIT",
  "country_code": "BR", /* ISO 3166-1 alfa-2 */
  "country_name": "BRAZIL",
  "info": "nubank.com.br"
}

HTTP Status 401 - Unauthorized

Quando o HTTP status do retorno da análise de risco for igual à 401, significa que o Header de autenticação estava inválido.

Nesse caso, o JSON da resposta será vazio.

HTTP Status 422 - Unprocessable Entity

Quando o HTTP status do retorno da análise de risco for igual à 422, significa que algum dado enviado para a análise não está no formato esperado pela API.

Demais HTTP Status Codes

Os demais status codes não são erros esperados pela API, e devem ser comunicados pelo nosso canal de suporte para maiores investigações e esclarecimentos.