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

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

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

Response Body

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

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

Request Body: 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: EXAMPLE_API_KEY"

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

Buscar Transactions

Response Body: 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:

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