chargeback-docs

Enriquecimento de Transação

Enriquecimento de Dados

Enviaremos uma notificação webhook (HTTP POST) no seguinte formato:

{
    "event": "transaction",
    "payload": {
        "contractDisputeId": "d492bhhnshts7160i5g0", // ID Interno da Tupi
        "transactionIdentifier": "431220079801", // TID (pode ser null)
        "acquirerReferenceNumber": "20099984311312200798013" // ARN (pode ser null)
    }
}

Campos da Notificação Webhook

Campo	Tipo	Obrigatório	Descrição
`event`	string	Sim	Identificador do tipo de evento. Sempre “transaction” para solicitações de enriquecimento de transação
`payload`	object	Sim	Container para os dados de identificação da transação
`payload.contractDisputeId`	string	Sim	Identificador único interno da Tupi para o contrato de disputa
`payload.transactionIdentifier`	string	Não	ID da Transação (TID). Pode ser null dependendo da bandeira do cartão
`payload.acquirerReferenceNumber`	string	Não	Número de Referência do Adquirente (ARN). Pode ser null dependendo da bandeira do cartão

Importante: O transactionIdentifier (TID) ou acquirerReferenceNumber (ARN) sempre será fornecido, embora um deles possa ser null dependendo da bandeira do cartão. Você deve usar o identificador que estiver disponível para buscar a transação em seu sistema.

Você deve então nos enviar uma requisição HTTP POST para a URL de callback fornecida durante a configuração (entre em contato conosco se não tiver certeza de qual endpoint usar).

{
    "type": "transaction",
    "data": {
        "authorizationCode": "135644",
        "authorizationStatusCode": "00",
        "authorizationCurrencyCode": "986", // ISO 4217
        "authorizationSystemTraceAuditNumber": "123456789",
        "authorizationDate": "2025-01-01T00:00:00.000Z",
        "authorizationAmount": 10000,// em centavos = 100.00
 
        "acquirerReferenceNumber": "25699994259255249310221", // ARN
        "transactionIdentifier": "405088518881", // TID
        "terminalIdentifier": "00281236",
        "cardNumber": "50677*****6581" , // mascarado: manter os primeiros 6 dígitos e os últimos 4 dígitos
        "paymentPlan": 1, // int

        // dica: mesmo que enviado pela bandeira
        "entryMode": "5",
        "electronicCommerceIndicator": "05", // ECI

        "installments": [
            {
                "acquirerReferenceNumber": "25699994259255249310222", // ARN
                "installmentNumber": 1, // int
                "installmentDate": "2025-01-01T00:00:00.000Z",
                "amount": 10000, // em centavos = 100.00

				// enum: settled | scheduled | canceled | confirmed | sent
                "issuerSettlementStatus": "settled",
				
				// enum: settled | scheduled | canceled
                "merchantSettlementStatus": "settled"
            }
        ],
        "vouchers": [
            {
                "acquirerReferenceNumber": "25699994259255249310223", // ARN
                "amount": 100, // em centavos = 1.00
                "voucherDate": "2025-01-01T00:00:00.000Z",
                "installmentNumber": 1
            }
        ]
    }
}

Campos da Requisição de Callback

Campo	Tipo	Obrigatório	Descrição
`type`	string	Sim	Identificador do tipo de requisição. Sempre “transaction” para dados de transação
`data`	object	Sim	Container para os dados da transação
`data.authorizationCode`	string	Sim	Código de autorização da transação
`data.authorizationStatusCode`	string	Não	Código de status da autorização (ex: “00” para aprovado)
`data.authorizationCurrencyCode`	string	Sim	Código da moeda no formato ISO 4217 (ex: “986” para BRL)
`data.authorizationSystemTraceAuditNumber`	string	Sim	STAN ou NSU da autorização
`data.authorizationDate`	string	Sim	Data e hora da autorização no formato ISO 8601
`data.authorizationAmount`	number	Sim	Valor da autorização em centavos (ex: 10000 = 100.00)
`data.acquirerReferenceNumber`	string	Sim	Número de Referência do Adquirente (ARN)
`data.transactionIdentifier`	string	Não	ID da Transação (TID)
`data.terminalIdentifier`	string	Não	Identificador do terminal onde a transação ocorreu
`data.cardNumber`	string	Sim	Número do cartão mascarado (primeiros 6 e últimos 4 dígitos visíveis)
`data.paymentPlan`	number	Sim	Identificador do plano de pagamento
`data.entryMode`	string	Sim	Modo de entrada do cartão (mesmo enviado pela bandeira do cartão)
`data.electronicCommerceIndicator`	string	Sim	Indicador de Comércio Eletrônico (ECI)
`data.installments`	array	Sim	Array de objetos de parcelas da transação
`data.vouchers`	array	Não	Array de objetos de vouchers da transação

Campos do Objeto Installment

Campo	Tipo	Obrigatório	Descrição
`acquirerReferenceNumber`	string	Sim	ARN para esta parcela específica
`installmentNumber`	number	Sim	Número sequencial da parcela
`installmentDate`	string	Sim	Data da parcela no formato ISO 8601
`amount`	number	Sim	Valor da parcela em centavos
`issuerSettlementStatus`	string	Sim	Status de liquidação com o emissor. Valores: “settled”, “scheduled”, “canceled”, “confirmed”, “sent”
`merchantSettlementStatus`	string	Sim	Status de liquidação com o comerciante. Valores: “settled”, “scheduled”, “canceled”

Campos do Objeto Voucher

Campo	Tipo	Obrigatório	Descrição
`acquirerReferenceNumber`	string	Sim	ARN para este voucher específico
`amount`	number	Sim	Valor do voucher em centavos
`voucherDate`	string	Sim	Data do voucher no formato ISO 8601
`installmentNumber`	number	Sim	Número da parcela associada

Valores de Entry Mode

O campo entryMode indica como as informações do cartão foram capturadas durante a transação. Abaixo estão os valores possíveis organizados por bandeira do cartão.

Modos de Entrada Visa

Código	Descrição
00	Terminal not used
01	Manual key entry
02	Magnetic stripe read
03	Optical code
04	Optical Character Recognition (OCR) read. Not used - reserved for future use
05	Integrated circuit card read
06	Track 1 read (Not used for Visa Electron)
07	Proximity payment using VSDC chip data rules
10	Credential on File
84	Reserved
90	Magnetic stripe read and exact content of Track 1 or Track 2 included (CVV check is possible)
91	Proximity payment using magnetic stripe data rules
95	Integrated circuit card; CVV or iCVV may not be possible

Modos de Entrada Mastercard

Código	Descrição
00	Terminal not used
01	Manual key entry
02	Magnetic stripe read
03	Optical code
04	Optical Character Recognition (OCR) read. Not used - reserved for future use
05	Integrated circuit card read
06	Track 1 read. Not used for Visa and Visa Electron card transactions
07	Proximity payment using VSDC chip data rules
09	PAN/Token entry via e-commerce containing DSRP cryptogram in DE55
10	Credential on File
79	A hybrid terminal with an online connection to the acquirer failed
80	Chip card at chip-capable terminal was unable to process transaction using data on the chip; therefore, the terminal defaulted to the magnetic stripe-read PAN
81	PAN/Token entry via electronic commerce with optional Identity Check-AAV or DSRP cryptogram in UCAF
82	PAN Auto Entry via Server (issuer, acquirer, or third party vendor system)
90	Magnetic stripe read and exact content of Track 1 or Track 2 included (CVV check is possible)
91	Proximity payment using magnetic stripe data rules
95	Integrated circuit card; CVV or iCVV may not be possible

Modos de Entrada Elo

Código	Descrição
00	No terminal used
01	Key entered
02	Partial magnetic stripe read
03	Bar code read
04	Optical read
05	Chip
07	E-commerce
10	Store card account
81	Radio Frequency Identification - magnetic stripe
82	Mobile commerce
83	Radio Frequency Identification - chip
85	Chip fallback
86	Mudança de interface Contactless
90	Voice authorization
91	Voice Response Unit
92	Batch authorization
93	Batch authorization Cash Access

Valores de Indicador de Comércio Eletrônico

O campo electronicCommerceIndicator (ECI) indica o nível de segurança de uma transação de e-commerce. Abaixo estão os valores possíveis organizados por bandeira do cartão.

Indicadores de Comércio Eletrônico Visa

Código	Descrição
1	Mail/Phone Order (MO/TO)
2	Recurring transaction
3	Installment payment
4	Unknown classification/other mail order
5	Secure Electronic Commerce Transaction
6	Non-Authenticated Security Transaction at a 3-DSecure-capable merchant, and merchant attempted to authenticate the cardholder using 3-D secure
7	Non-Authenticated Security Transaction
8	Non-secure transaction
9	For optional regional use only

Indicadores de Comércio Eletrônico Mastercard

Código	Descrição
210	Present in unauthenticated transactions, or in transactions where an Identity Check merchant has chosen not to undertake Identity Check , or where Identity Check failed authentication and the merchant desires to proceed with the transaction. Alsopresent in transactions with a DTVC
211	Mastercard ® Identity Check transaction. UCAF data contains either an AttemptsAAV or a Non-Low Risk AAV for Mastercard ® Identity Check
212	Mastercard ® Identity Check transaction. UCAF data contains either an AttemptsAAV or a Non-Low Risk AAV for Mastercard ® Identity Check
214	Mastercard ® Identity Check where merchant has chosen to share data to generateinsights within the authorization (used in Identity Check Insights transactions).Insights provided to the Issuer in DE 48, subelement 56
216	Mastercard ® Identity Check transaction. Merchant Risk Based Decisioning
217	Mastercard ® Identity Check Merchant Initiated Transactions
242	Authenticated tokenized transaction with DSRP cryptogram. Transaction is noteligible for fraud-related chargeback by the issuer
246	Tokenized transaction with DSRP cryptogram
247	Tokenized Merchant Initiated Transaction

Indicadores de Comércio Eletrônico Elo

Código	Descrição
00	Desconhecido/Não Especificado/Loja não participa do programa
01	Transação não é uma transação de e-commerce
04	Transação com autenticação In App
05	Portador Autenticado pelo Emissor
06	Tentativa de Autenticação do Portador pelo Domínio do Credenciador
07	Transação de eCommerce Não Autenticada