# QI Tech — Risk Solutions › Antifraude transacional de cartão

Documentação da QI Tech em texto corrido, para colar em um LLM.
Fonte: https://docs.qitech.com.br
5 página(s).

Índice:
- Alertas de Portadores (/documentation/caas/card_issuance/alerts)
- Status HTTP (/documentation/caas/card_issuance/http_status)
- Introdução (/documentation/caas/card_issuance/introduction)
- Padrões (/documentation/caas/card_issuance/standards)
- Transaction (/documentation/caas/card_issuance/transaction)

---

# Alertas de Portadores

URL: /documentation/caas/card_issuance/alerts

Os alertas gerados pela ferramenta antifraude são notificados por meio de Webhook. Para tanto, é necessário, por meio da equipe do [suporte](mailto:suporte.caas@qitech.com.br), 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

Request Body

```json
    {
        "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 acima 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

```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

---

# Status HTTP

URL: /documentation/caas/card_issuance/http_status

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

Status HTTP | Significado | Descrição
---------- | ------- | ---------------------------------
400 | Bad Request | A requisição enviada possui algum erro de formatação. Na maioria dos casos, retornamos no corpo da mensagem uma explicação de onde está o erro.
401 | Unauthorized | Houve algum problema na autenticação, verifique se a API Key está correta e no header correto, de acordo com a seção Autenticação .
403 | Forbidden | O endpoint acessado é de uso interno e não está disponível para esta API Key.
404 | Not Found | O dado requisitado não foi encontrado usando a chave utilizada. Este status também é retornado quando um endpoint inválido é requisitado.
405 | Method Not Allowed | O método HTTP utilizado não se aplica ao endpoint utilizado.
406 | Not Acceptable | Os dados enviados no corpo da requisição são inválidos. Em geral, isso significa que os dados enviados não são um JSON válido.
409 | Conflict | O id da requisição corresponde a um id já processado anteriormente. Este status é retornado no caso de requisições duplicadas enviadas ao servidor.
500 | Internal Server Error | Tivemos um problema para processar esta requisição, ao encontrarmos esse erro nossos especialistas são automaticamente notificados e iniciam a análise e solução imediatamente.
503 | Service Unavailable | Você se deparou com uma indisponibilidade, planejada ou não, de infraestrutura dos nossos servidores.

---

# Introdução

URL: /documentation/caas/card_issuance/introduction

Bem vindo à API de Prevenção a Fraudes em emissão de cartões da QI Tech! 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.

:::info **Atenção**

Atenção, esta API é direcionada para emissores de cartão, ou seja, empresas que dão o cartão na mão do portador para que ele possa transacionar. Ela tem como objetivo realizar toda a análise de segurança nas transações do seu cliente, evitando fraudes e outros tipos de incidentes (Transações decorrentes de assaltos, por exemplo).
:::

Abaixo, 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. As URLs base das APIs são:

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

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.  
:::

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:

Mínimo | Máximo | Decisão
------ | ------ | -------
10000 | - | automatically_approved
0 | 9999 | automatically_declined

## Somente HTTPS

Por questão de segurança, toda a comunicação com as APIs da QI Tech deve ser realizada utilizando a comunicação HTTPS. Para evitar que, por desatenção ou outro motivo, sejam feitas 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:

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

> Substitua a API key 'EXAMPLE-OF-API-KEY' 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: EXAMPLE-OF-API-KEY`

:::info **Atenção**

Você deve substituir EXAMPLE-OF-API-KEY com a API Key recebida do suporte.
:::

---

# Padrões

URL: /documentation/caas/card_issuance/standards

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
```

---

# Transaction

URL: /documentation/caas/card_issuance/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

Request Body

```json
{
  "id": "678",
  "cardholder_id": "b812da2e-e6be-4712-8e57-6f3f2791625b",
  "group_id" : "8507884b-c30f-4b45-951c-f0bf366926fc",
  "amount": 13725,
  "currency": "BRL",
  "brl_converted_amount": 13725,
  "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**:

Resultado | Descrição
:---------: | ---------
automatically_approved | Recomenda-se que esta transação seja aprovada
automatically_declined | Recomenda-se que esta transação seja reprovada
not_analyzed | A consulta foi enviada com a flag de análise falsa, o que significa que nossos sistemas não deverão retornar parecer

nome | tipo | descrição | 
:----: | :----: | ---------
id | string | *(obrigatório)* Identificador da transação no sistema do cliente. **É essencial que este número seja único para cada processo de autorização**
cardholder_id | string | *(obrigatório)* Identificador do portador no sistema do cliente - Conforme cadastrado na API de Onboarding
group_id | string | *(opcional)* Identificador de qual grupo ou categoria aquele usuário pertence dentro do sistema do cliente
amount | inteiro | *(obrigatório)* O valor da transação - conforme descrição da seção "Padrões"
currency | string | *(obrigatório)* A moeda utilizada na transação - ISO 4217 e ApplicationCurrencyCode da 8583
brl_converted_amount | inteiro | *(obrigatório)* O valor da transação convertido para reais - conforme descrição da seção "Padrões"
installments | inteiro | *(obrigatório)* O número de parcelas utilizado na transação
authorization_date | datetime | *(obrigatório)* A data e hora de início da transação, com fuso horário
authorization_type | enumerador | *(obrigatório)* Transação de autorização ou de pré-autorização?
transaction_type | enumerador | *(obrigatório)* Crédito, Débito ou Voucher
pan_entry_mode | enumerador | *(obrigatório)* Modo de entrada do PAN - Chip, Digitada, Tarja, Fallback, Contactless - Campo proveniente da ISO 8583 (DE 22 - Sub Field 1)
pin_sent | booleano | *(obrigatório)* Foi inserida uma senha no terminal? - Campo proveniente do entry_mode da ISO 8583
source_account | enumerador | *(opcional)* O valor da transação deve ser retirado da fatura, da conta corrente ou da poupança - Campo proveniente do Processing Code da ISO 8583
location.latitude | number | *(opcional)* A latitude onde a transação ocorre - Caso haja uma celular atrelado ou haja outro meio de capturar a localização
location.longitude | number | *(opcional)* A longitude onde a transação ocorre
terminal.id | string | *(opcional)* O identificador do terminal enviado pela adquirente na mensageria de autenticação
terminal.country_code | string | *(obrigatório)* O código do país do terminal, enviado na mensagem de autorização conforme ISO 3166-1 alpha-3, campo proveniente de Terminal Country Code da ISO 8583
terminal.terminal_type | string | *(obrigatório)* O tipo de terminal conforme recebido na mensageria de autorização - Campo proveneiente de TerminalType da ISO 8583
terminal.pin_entry_capability | boolean | *(obrigatório)* Existe a possibilidade de inserir a senha do cartão no terminal? - Campo proveniente de TerminalPINEntryCapability da ISO 8583
terminal.magnetic_stripe_capability | boolean | *(opcional)* O terminal é capaz de ler tarja magnética? - Campo TerminalPANEntryCapability (DE 123) da ISO 8583
terminal.contactless_capability | boolean | *(opcional)* O terminal é capaz de iniciar transações contactless? - Campo TerminalPANEntryCapability (DE 123) da ISO 8583
terminal.chip_capability | boolean |*(obrigatório)* O terminal é capaz de iniciar transações utilizando o chip EMV? - Campo TerminalPANEntryCapability (DE 123) da ISO 8583
merchant.acquirer_id | string | *(obrigatório)* O identificador da adquirente conforme mensageria de autorização - Campo Acquirer Identifier (DE 32) da ISO 8583
merchant.merchant_id | string | *(obrigatório)* O identificador do lojista na adquirente conforme mensageria de autorização - Campo Merchant Identifier da ISO 8583
merchant.name | string | *(opcional)* O nome do lojista de acordo com a mensageria de autorização - Campo Merchant Name da ISO 8583
merchant.street | string | *(opcional)* A rua do endereço do lojista - Campo Card Acceptor Street Address
merchant.city | string | *(opcional)* A cidade do endereço do lojista - Campo Card Acceptor City
merchant.region | string | *(opcional)* A cidade do endereço do lojista - Campo Card Acceptor Region Code
merchant.postal_code | string | *(opcional)* A cidade do endereço do lojista - Campo Card Acceptor Postal Code
merchant.mcc | string | *(obrigatório)* Merchant Category Code, de acordo com a ISO 18245 e ISO 8583
card.brand | enumerador | *(obrigatório)* A bandeira do cartão (visa, mastercard, elo...)
card.category | enumerador | *(obrigatório)* A categoria do cartão (classic, gold, platinum, black, infinite, corporate)
card.issuing_date | datetime | *(obrigatório)* A data e hora quando o cartão foi emitido, com fuso horário
card.unblock_date | datetime | *(opcional)* A data e hora quando o cartão foi desbloqueado pelo portador, com fuso horário
card.expiration_date | date | *(obrigatório)* A data de vencimento do cartão (Último dia do mês)
card.bin | string | *(obrigatório)* O bin do cartão sendo utilizado
card.last4 | string | *(obrigatório)* Os quatro últimos dígitos do cartão, utilizados para identificar o cartão dentro do emissor
card.total_credit_limit | number | *(opcional)* O limite total de crédito concedido ao portador. Caso o cartão seja pré-pago, o valor existente de crédito no cartão
card.used_credit_limit | number | *(opcional)* O valor do limite já utilizado (Antes da transação em questão)
card.issuer_country_code | string | *(obrigatório)* O país do emissor de acordo com a ISO 3166-1 alpha-3
transaction_status | enumerador | *(opcional)* O status da transação, caso esta venha com flag ***analyze=false*** e decisão de autorização já tenha sido tomada.
response_code | enumerador | *(opcional)* O response code da transação conforme o campo Response Code da ISO 8583, caso esta venha com flag ***analyze=false*** e decisão de autorização já tenha sido tomada.

## 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

enumerador | significado
---------- | -----------
authorization | Uma autorização de compra - MTI x1xx (DMS) e x2xx (SMS)
pre_authorization | Uma pré autorização para reserva de limite no cartão (Hotel, Locação de Veículos, Locação de Equipamentos, Máquinas de Combustível) - MTI x1xx (DMS) e Transaction Type (2 primeiros dígitos do Processing Code) "60"
reversal | Uma autorização de cancelamento (Para liberar limite no cartão e posteriormente prosseguir com o Clearing/BASE II) - MTI x4xx

## transaction_type
enumerador | significado
---------- | ----------
credit | Uma transação passada na função crédito
debit | Uma transação passada na função débito
prepaid | Uma transação passada na função pré-pago

## pan_entry_mode
enumerador | ISO 8583 | significado
---------- | -------- | -----------
unknown | 00 | PAN entry mode desconhecido.
typed | 01 | PAN inserido manualmente (digitado).
bar_code | 03 | PAN inserido por meio de leitora de código de barras
ocr | 04 | PAN inserido por meio de OCR (Optical Character Recognition)
chip | 05 | PAN inserido por cartão com circuito integrado (Chip)
track_1 | 06 | PAN inserido pela Track 1 do cartão de tarja
contactless | 07 | PAN inserido por meio de Contactless EMV
fallback_typed | 79 | Foi tentado utilizar o leitor de cartão ou de tarja do dispositivo e o cartão mas não foi possível processar a transação com aquela informação (Possivelmente um problema no dispositivo ou no cartão), foi então digitada o PAN. Em alguns casos a adquirente não está homologada para utilizar o CHIP ou a tarja e envia este código.
fallback_magnetic_stripe | 80 | Foi tentado utilizar o leitor de cartão do dispositivo e o cartão mas não foi possível processar a transação com aquela informação (Possivelmente um problema no dispositivo ou no cartão), foi então utilizada a tarja magnética do cartão.
ecommerce | 81 | Transação de e-commerce / não presencial
magnetic_stripe | 90 | Transação de tarja (Cartão não possui chip ou dispositivo não possui leitor/não foi homologado)

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

## source_account
enumerador | ISO 8583 | significado
---------- | -------- | -----------
default | 00 | Padrão ou não especificado
saving_account | 10 | Conta poupança
checking_account | 20 | Conta corrente
credit_facility | 30 | Fatura
universal_account | 40 | Universal Account
investment_account | 50 | Conta de Investimento
electronic_purse | 60 | Saldo armazenado no chip do cartão (Electronic Purse)

## brand
enumerador | significado
---------- | -----------
visa | Visa
mastercard | MasterCard
diners_club | Diners Club
elo | Elo
american_express | American Express

## category
enumerador | significado
---------- | -----------
classic | Classic
gold | Gold
platinum | Platinum
black | Black/Infinite
travel | Travel
corporate | Corporate/Business
prepaid | Pré-pago

## terminal_type

enumerador | significado
---------- | -----------
0 | Unknown
1 | No terminal used
2 | Magnetic stripe reader
3 | Bar code (reserved for future use)
4 | Optical Character Recognition (reserved for future use)
5 | Magnetic stripe reader and EMV specification compatible integrated circuit card (ICC) reader
6 | Key entry only
7 | Magnetic stripe reader and key entry
8 | Magnetic stripe reader and key entry and EMV-compatible ICC reader
9 | EMV compatible ICC reader

## Enviar uma Transaction

Request Body

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

Response Body

```json
  {
    "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

Request Body: Na autorização de uma transaction

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

Request Body: No cancelamento parcial de uma transaction

```json
{
  "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`

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

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

## Buscar Transactions

Response Body: Lista de objetos Transaction.

```json
[
  {
    "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:

Parâmetro | Padrão | Descrição
--------- | ----------- | --------------
initial_date | null | Primeira data que deve ser retornada a partir do campo transaction_date
final_date | null | Última data que deve ser retornada a partir do campo transaction_date
cardholder_id | null | Identificador, no emissor, do portador do cartão
page_number | 0 | Número da página de resultados desejada, iniciando em zero
page_rows | 50 | Número de objetos máximo a ser retornados em uma consulta