Skip to main content

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:

ResultadoDescrição
automatically_approvedRecomenda-se que esta transação seja aprovada
automatically_declinedRecomenda-se que esta transação seja reprovada
not_analyzedA consulta foi enviada com a flag de análise falsa, o que significa que nossos sistemas não deverão retornar parecer
nometipodescrição
idstring(obrigatório)
Identificador da transação no sistema do cliente.
É essencial que este número seja único para cada processo de autorização
cardholder_idstring(obrigatório)
Identificador do portador no sistema do cliente - Conforme cadastrado na API de Onboarding
group_idstring(opcional)
Identificador de qual grupo ou categoria aquele usuário pertence dentro do sistema do cliente
amountinteiro(obrigatório)
O valor da transação - conforme descrição da seção "Padrões"
currencystring(obrigatório)
A moeda utilizada na transação - ISO 4217 e ApplicationCurrencyCode da 8583
brl_converted_amountinteiro(obrigatório)
O valor da transação convertido para reais - conforme descrição da seção "Padrões"
installmentsinteiro(obrigatório)
O número de parcelas utilizado na transação
authorization_datedatetime(obrigatório)
A data e hora de início da transação, com fuso horário
authorization_typeenumerador(obrigatório)
Transação de autorização ou de pré-autorização?
transaction_typeenumerador(obrigatório)
Crédito, Débito ou Voucher
pan_entry_modeenumerador(obrigatório)
Modo de entrada do PAN - Chip, Digitada, Tarja, Fallback, Contactless - Campo proveniente da ISO 8583 (DE 22 - Sub Field 1)
pin_sentbooleano(obrigatório)
Foi inserida uma senha no terminal? - Campo proveniente do entry_mode da ISO 8583
source_accountenumerador(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.latitudenumber(opcional)
A latitude onde a transação ocorre - Caso haja uma celular atrelado ou haja outro meio de capturar a localização
location.longitudenumber(opcional)
A longitude onde a transação ocorre
terminal.idstring(opcional)
O identificador do terminal enviado pela adquirente na mensageria de autenticação
terminal.country_codestring(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_typestring(obrigatório)
O tipo de terminal conforme recebido na mensageria de autorização - Campo proveneiente de TerminalType da ISO 8583
terminal.pin_entry_capabilityboolean(obrigatório)
Existe a possibilidade de inserir a senha do cartão no terminal? - Campo proveniente de TerminalPINEntryCapability da ISO 8583
terminal.magnetic_stripe_capabilityboolean(opcional)
O terminal é capaz de ler tarja magnética? - Campo TerminalPANEntryCapability (DE 123) da ISO 8583
terminal.contactless_capabilityboolean(opcional)
O terminal é capaz de iniciar transações contactless? - Campo TerminalPANEntryCapability (DE 123) da ISO 8583
terminal.chip_capabilityboolean(obrigatório)
O terminal é capaz de iniciar transações utilizando o chip EMV? - Campo TerminalPANEntryCapability (DE 123) da ISO 8583
merchant.acquirer_idstring(obrigatório)
O identificador da adquirente conforme mensageria de autorização - Campo Acquirer Identifier (DE 32) da ISO 8583
merchant.merchant_idstring(obrigatório)
O identificador do lojista na adquirente conforme mensageria de autorização - Campo Merchant Identifier da ISO 8583
merchant.namestring(opcional)
O nome do lojista de acordo com a mensageria de autorização - Campo Merchant Name da ISO 8583
merchant.streetstring(opcional)
A rua do endereço do lojista - Campo Card Acceptor Street Address
merchant.citystring(opcional)
A cidade do endereço do lojista - Campo Card Acceptor City
merchant.regionstring(opcional)
A cidade do endereço do lojista - Campo Card Acceptor Region Code
merchant.postal_codestring(opcional)
A cidade do endereço do lojista - Campo Card Acceptor Postal Code
merchant.mccstring(obrigatório)
Merchant Category Code, de acordo com a ISO 18245 e ISO 8583
card.brandenumerador(obrigatório)
A bandeira do cartão (visa, mastercard, elo...)
card.categoryenumerador(obrigatório)
A categoria do cartão (classic, gold, platinum, black, infinite, corporate)
card.issuing_datedatetime(obrigatório)
A data e hora quando o cartão foi emitido, com fuso horário
card.unblock_datedatetime(opcional)
A data e hora quando o cartão foi desbloqueado pelo portador, com fuso horário
card.expiration_datedate(obrigatório)
A data de vencimento do cartão (Último dia do mês)
card.binstring(obrigatório)
O bin do cartão sendo utilizado
card.last4string(obrigatório)
Os quatro últimos dígitos do cartão, utilizados para identificar o cartão dentro do emissor
card.total_credit_limitnumber(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_limitnumber(opcional)
O valor do limite já utilizado (Antes da transação em questão)
card.issuer_country_codestring(obrigatório)
O país do emissor de acordo com a ISO 3166-1 alpha-3
transaction_statusenumerador(opcional)
O status da transação, caso esta venha com flag analyze=false e decisão de autorização já tenha sido tomada.
response_codeenumerador(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

enumeradorsignificado
authorizationUma autorização de compra - MTI x1xx (DMS) e x2xx (SMS)
pre_authorizationUma 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"
reversalUma autorização de cancelamento (Para liberar limite no cartão e posteriormente prosseguir com o Clearing/BASE II) - MTI x4xx

transaction_type

enumeradorsignificado
creditUma transação passada na função crédito
debitUma transação passada na função débito
prepaidUma transação passada na função pré-pago

pan_entry_mode

enumeradorISO 8583significado
unknown00PAN entry mode desconhecido.
typed01PAN inserido manualmente (digitado).
bar_code03PAN inserido por meio de leitora de código de barras
ocr04PAN inserido por meio de OCR (Optical Character Recognition)
chip05PAN inserido por cartão com circuito integrado (Chip)
track_106PAN inserido pela Track 1 do cartão de tarja
contactless07PAN inserido por meio de Contactless EMV
fallback_typed79Foi 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_stripe80Foi 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.
ecommerce81Transação de e-commerce / não presencial
magnetic_stripe90Transaçã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

enumeradorISO 8583significado
default00Padrão ou não especificado
saving_account10Conta poupança
checking_account20Conta corrente
credit_facility30Fatura
universal_account40Universal Account
investment_account50Conta de Investimento
electronic_purse60Saldo armazenado no chip do cartão (Electronic Purse)

brand

enumeradorsignificado
visaVisa
mastercardMasterCard
diners_clubDiners Club
eloElo
american_expressAmerican Express

category

enumeradorsignificado
classicClassic
goldGold
platinumPlatinum
blackBlack/Infinite
travelTravel
corporateCorporate/Business
prepaidPré-pago

terminal_type

enumeradorsignificado
0Unknown
1No terminal used
2Magnetic stripe reader
3Bar code (reserved for future use)
4Optical Character Recognition (reserved for future use)
5Magnetic stripe reader and EMV specification compatible integrated circuit card (ICC) reader
6Key entry only
7Magnetic stripe reader and key entry
8Magnetic stripe reader and key entry and EMV-compatible ICC reader
9EMV 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âmetroPadrãoDescrição
initial_datenullPrimeira data que deve ser retornada a partir do campo transaction_date
final_datenullÚltima data que deve ser retornada a partir do campo transaction_date
cardholder_idnullIdentificador, no emissor, do portador do cartão
page_number0Número da página de resultados desejada, iniciando em zero
page_rows50Número de objetos máximo a ser retornados em uma consulta