Introdução

Bem vindo à API de Prevenção a Fraudes em emissão de cartões da Zaig! Você pode utilizar a nossa API para acessar os endpoints, a fim de receber a resposta de uma transação, além de utilizar para atualizar a situação de uma transação.

Ao lado, você pode observar a implementação da API utilizando cUrl. Com isso você possui exemplos para poder adaptar adequadamente à linguagem de programação da sua preferência.

Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso suporte e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

Ambientes

Possuímos dois ambientes para os nossos clientes. A URL base das APIs são:

• Produção - https://api.caas.qitech.app/card_issuance/
• Sandbox - https://api.sandbox.caas.qitech.app/card_issuance/

No ambiente de Sandbox, as análises enviadas não são cobradas e são respondidas de acordo com regras pré estabelecidas.

Para a análise de uma transação, a seguinte regra é aplicada sobre o valor da transação:

Somente HTTPS

Por questão de segurança, toda a comunicação com as APIs da Zaig devem ser realizadas utilizando a comunicação HTTPS. Para garantir que, por desatenção ou qualquer outro motivo, não ocorram chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas.

Autenticação

Para autenticar uma chamada, utilize o código seguinte:

# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
  -H "Authorization: TESTETESTETESTE"

Substitua a API key 'TESTETESTETESTE' com a sua chave adquirida com o nosso suporte.

Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br.

Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:

Authorization: TESTETESTETESTE

Transaction

No momento em que o portador iniciar uma transação, os dados deverão ser enviados para o nosso servidor, de maneira que possamos realizar uma análise do risco envolvida naquele conjunto de dados.

Definição do Objeto

Exemplo

{
  "id": "678",
  "cardholder_id": "b812da2e-e6be-4712-8e57-6f3f2791625b",
  "group_id" : "8507884b-c30f-4b45-951c-f0bf366926fc",
  "amount": 13725,
  "currency": "BRL",
  "installments": 6,
  "authorization_date": "2019-11-10T13:25:42.123-03:00",
  "authorization_type": "authorization",
  "transaction_type": "credit",
  "pan_entry_mode": "chip",
  "pin_sent": true,
  "source_account": "saving_account",
  "location": {
    "latitude": -45.2753548,
    "longitude": -15.24587
  },
  "terminal": {
    "id": "123456",
    "country_code": "BRA",
    "terminal_type": "2",
    "pin_entry_capability": true,
    "magnetic_stripe_capability": true,
    "contactless_capability": false,
    "chip_capability": true
  },
  "merchant": {
    "acquirer_id": "250",
    "merchant_id": "123456",
    "name": "VASP LINHAS AEREAS",
    "street" : "RUA CMDTE X, 127",
    "city" : "SAO PAULO, SP",
    "region": "BRA",
    "postal_code": "04570-140",
    "mcc": "3036"
  },
  "card": {
    "brand": "visa",
    "category": "black",
    "issuing_date": "2019-10-08T07:13:12.333-03:00",
    "unblock_date": "2019-10-12T07:13:12.333-03:00",
    "expiration_date": "2019-12-31",
    "bin": "498406",
    "last4": "1234",
    "total_credit_limit": 2500000,
    "used_credit_limit": 732625,
    "issuer_country_code": "BRA"
  },
  "transaction_status" : "authorized",
  "response_code": "05"
}

Uma transação deve ser enviada para a API antes da autorização da transação e pode ser utilizada para se tomar a decisão de gerar (ou não) um código de autorização. Os dados enviados também podem ser utilizados para a geração de alertas baseados no histórico de transações do portador, de maneira que caso haja um comportamento diferente do esperado, o alerta dispare uma ação adequada a fim de mitigar o impacto das transações.

Os status de fraude (fraud_status e transaction_status) representam, respectivamente, a decisão retornada pelo modelo sobre aquela transação e o dado se a transação foi efetivada, cancelada ou se tornou uma disputa.

Os seguintes status são utilizados no transaction_status:

• not_authorized
• authorized
• cleared
• cancelled
• partially_cancelled
• chargeback
• partial_chargeback

Os seguintes status são utilizados no fraud_status:

• automatically_approved
• automatically_declined
• not_analyzed

Abaixo estão listados os significados de cada uma das decisões, devolvida na flag fraud_status:

Enumeradores

Os enumeradores do objeto de transação de cartão são authorization_type, transaction_type, pan_entry_mode, source_account, brand e category. Os valores possíveis de cada um podem ser vistos abaixo:

authorization_type

transaction_type

pan_entry_mode

Existem outros valores de PAN_ENTRY_MODE, entretanto eles geralmente não são utilizados.

source_account

brand

category

terminal_type

Enviar uma Transaction

Exemplo de Request

  {
    "id": "12345",
    ...
  }

Exemplo de Retorno

  {
    "id": "12345",
    "fraud_status": "automatically_approved"
  }

Para realizar a avaliação de uma transação, basta enviar um objeto do tipo Transaction ao seguinte endpoint com a flag setada adequadamente:

POST https://api.production-sa.zaig.com.br/card_issuance/transaction?analyze=true

O parâmetro analyze existe para evitar que transações que não precisam ser analisadas passem pelos motores de fraude, sujando a base de dados. O valor padrão deste parâmetro é true, de maneira que somente transações explícitamente marcadas não serão analisadas.

Atualizar o status de uma Transaction

Corpo da requisição - Na autorização de uma transaction

{
  "transaction_status": "authorized",
  "response_code": "05"
}

Corpo da requisição - No cancelamento parcial de uma transaction

{
  "transaction_status": "partially_cancelled",
  "partial_amount" : 3000,
  "response_code": "05"
}

Para garantir a retroalimentação das regras e do modelo de inteligência artificial implementado, é necessário informar ao sistema quando as transações são canceladas. Para isso, requisições com o método PUT devem ser utilizadas, autenticadas normalmente:

PUT https://api.production-sa.zaig.com.br/card_issuance/transaction/123456

Recuperar uma Transaction

A fim de recuperar uma Transaction específica, basta realizar uma requisição GET. O resultado retornado é o json mais atualizado da Transaction em questão. Caso este identificador não esteja relacionado a nenhum objeto, o HTTP Status 404 é retornado.

GET https://api.production-sa.zaig.com.br/card_issuance/transaction/12345678

curl "https://api.production-sa.zaig.com.br/card_issuance/transaction/12345678"
  -H "Authorization: TESTETESTETESTE"

O comando acima retorna o JSON que representa um objeto de Transaction.

Buscar Transactions

Retorna um JSON que representa uma lista de objetos Transaction.

[
  {
    "id": "12345",
    ...
  },
  {
    "id": "12345",
    ...
  }
]

Caso seja necessário buscar uma Transaction, um GET com parâmetros de query poderá ser utilizado. O resultado retornado é um JSON que representa uma lista de Transaction. Caso nenhum objeto seja encontrado com os parâmetros enviados, o HTTP Status 200 é retornado com uma lista vazia no corpo da resposta.

GET https://api.production-sa.zaig.com.br/card_issuance/transactions?initial_date=2019-10-01&final_date=2019-10-05&page_number=2&page_rows=20

Os seguintes parâmetros podem ser utilizados para a busca:

Alertas de Portadores

Os alertas gerados pela ferramenta antifraude são notificados por meio de Webhook. Para tanto, é necessário, por meio da equipe do suporte, configurar um endereço do endpoint por onde vamos notificar as notificações e também um secret_token que será utilizado para assinar a requisição.

Nesta notificação enviaremos informações dos alertas gerados, bem como de qual portador se trata, para que o cliente possa tomar alguma ação, por exemplo, enviar um push notification para o portador.

Requisição

Exemplo de requisição

    {
        "alert_key": "123456",
        "cardholder_id": "ef47bc3f-61ac-4b85-ad67-0cfa3a422201",
        "company_name": "Cliente 1",
        "irregularity_type" : "fraud",
        "risk_level": "critical"
    }

A requisição possui o formato ao lado e notifica a abertura de um novo alerta para um Portador - descrito pelo cardholder_id

Assinatura do Webhook

Exemplo de cálculo de assinatura em Python

    hmac_obj = hmac.new(signature_key.encode('utf-8'), (endpoint + method + payload).encode('utf-8'), hashlib.sha1)
    return hmac_obj.hexdigest()

Para garantir que a requisição recebida no endpoint do webhook parte dos nossos servidores, uma assinatura HMAC é enviada no Header Signature, semelhante ao processo de autenticação.

Após realizar o cálculo do valor esperado da assinatura do lado do servidor, é necessário comparar a assinatura calculada com a enviada. Caso as assinaturas sejam compatíveis, isso significa que a requisição partiu dos nossos servidores e que é confiável.

Retentativas

A notificação é considerada realizada quando recebe como resposta um HTTP Status 200. Caso as notificações falhem, serão feitas 5 retentativas, com os seguintes intervalos, até que um 200 seja retornado ou as tentativas terminem:

• 30 segundos
• 60 segundos
• 120 segundos
• 240 segundos
• 360 segundos

Padrões

Para facilitar a integração e garantir a integridade da informação, foram definidos alguns padrões que são seguidos em toda a API.

Valores Monetários

Exemplos:

10000
12345
98741
1223
1
0

Os valores devem ser enviados como inteiro em centavos.

Data e Hora com Fuso Horário

Alguns exemplos:

2019-10-15T22:35:12-03:00
2018-05-01T13:32:11+00:00
2019-05-01T00:00:00+00:00

É representada conforme a ISO 8601. Neste caso, o fuso-horário é colocado logo após o horário e deve representar o fuso do local onde aquele dado será valido. Por exemplo, se um aluguel estiver marcado para começar às 09:30 no aeroporto de Brasília, o horário enviado deverá ser representado por 09:30-03:00, se o aluguel estiver marcado para começar às 09:30 em Manaus, deverá ser representado por 09:30-04:00.

A máscara utilizada para validação é a seguinte:

YYYY-MM-ddThh:mm:ss±hh:mm

Data e Hora sem Fuso Horario

Alguns exemplos:

2019-10-15T22:35:12Z
2018-05-01T13:32:11Z
2019-05-01T00:00:00Z

É representada conforme a ISO 8601. Dados que independem de fuso-horário deverão ser enviados sem ele, sempre em UTC, com a letra Z indicando que este dado está em UTC. O seguinte formato, portanto, será validado:

YYYY-MM-ddThh:mm:ssZ

Data

Alguns exemplos

2019-10-15
2019-01-01
2017-03-20

Status HTTP

Todas as APIs da Zaig utilizam a seguinte padronização nos status HTTP de retorno, de acordo com o RFC 7231: