chargeback-docs

Transaction Enrichment

Data Enrichment

We will send you a webhook notification (HTTP POST) in the following format:

{
    "event": "transaction",
    "payload": {
        "contractDisputeId": "d492bhhnshts7160i5g0", // Tupi Internal ID
        "transactionIdentifier": "431220079801", // TID (can be null)
        "acquirerReferenceNumber": "20099984311312200798013" // ARN (can be null)
    }
}

Webhook Payload Fields

Field	Type	Required	Description
`event`	string	Yes	Event type identifier. Always “transaction” for transaction enrichment requests
`payload`	object	Yes	Container for the transaction identification data
`payload.contractDisputeId`	string	Yes	Tupi’s internal unique identifier for the dispute contract
`payload.transactionIdentifier`	string	No	Transaction ID (TID). May be null depending on card brand
`payload.acquirerReferenceNumber`	string	No	Acquirer Reference Number (ARN). May be null depending on card brand

Important: Either transactionIdentifier (TID) or acquirerReferenceNumber (ARN) will always be provided, though one of them may be null depending on the card brand. You must use whichever identifier is available to look up the transaction in your system.

You must then send us an HTTP POST request to the callback URL provided during setup (contact us if you’re unsure which endpoint to use).

{
    "type": "transaction",
    "data": {
        "authorizationCode": "135644",
        "authorizationStatusCode": "00",
        "authorizationCurrencyCode": "986", // ISO 4217
        "authorizationSystemTraceAuditNumber": "123456789",
        "authorizationDate": "2025-01-01T00:00:00.000Z",
        "authorizationAmount": 10000,// in cents = 100.00
 
        "acquirerReferenceNumber": "25699994259255249310221", // ARN
        "transactionIdentifier": "405088518881", // TID
        "terminalIdentifier": "00281236",
        "cardNumber": "50677*****6581" , // masked: keep first 6 digits and last 4 digits
        "paymentPlan": 1, // int

        // tip: same as sent by the brand
        "entryMode": "5",
        "electronicCommerceIndicator": "05", // ECI

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

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

Callback Request Fields

Field	Type	Required	Description
`type`	string	Yes	Request type identifier. Always “transaction” for transaction data
`data`	object	Yes	Container for the transaction data
`data.authorizationCode`	string	Yes	Authorization code from the transaction
`data.authorizationStatusCode`	string	No	Status code from the authorization (e.g., “00” for approved)
`data.authorizationCurrencyCode`	string	Yes	Currency code in ISO 4217 format (e.g., “986” for BRL)
`data.authorizationSystemTraceAuditNumber`	string	Yes	STAN or NSU of authorization
`data.authorizationDate`	string	Yes	Date and time of authorization in ISO 8601 format
`data.authorizationAmount`	number	Yes	Authorization amount in cents (e.g., 10000 = 100.00)
`data.acquirerReferenceNumber`	string	Yes	Acquirer Reference Number (ARN)
`data.transactionIdentifier`	string	No	Transaction ID (TID)
`data.terminalIdentifier`	string	No	Terminal identifier where the transaction occurred
`data.cardNumber`	string	Yes	Masked card number (first 6 and last 4 digits visible)
`data.paymentPlan`	number	Yes	Payment plan identifier
`data.entryMode`	string	Yes	Card entry mode (same as sent by the card brand)
`data.electronicCommerceIndicator`	string	Yes	Electronic Commerce Indicator (ECI)
`data.installments`	array	Yes	Array of installment objects for the transaction
`data.vouchers`	array	No	Array of voucher objects for the transaction

Installment Object Fields

Field	Type	Required	Description
`acquirerReferenceNumber`	string	Yes	ARN for this specific installment
`installmentNumber`	number	Yes	Installment sequence number
`installmentDate`	string	Yes	Date of the installment in ISO 8601 format
`amount`	number	Yes	Installment amount in cents
`issuerSettlementStatus`	string	Yes	Settlement status with issuer. Values: “settled”, “scheduled”, “canceled”, “confirmed”, “sent”
`merchantSettlementStatus`	string	Yes	Settlement status with merchant. Values: “settled”, “scheduled”, “canceled”

Voucher Object Fields

Field	Type	Required	Description
`acquirerReferenceNumber`	string	Yes	ARN for this specific voucher
`amount`	number	Yes	Voucher amount in cents
`voucherDate`	string	Yes	Date of the voucher in ISO 8601 format
`installmentNumber`	number	Yes	Associated installment number

Entry Mode Values

The entryMode field indicates how the card information was captured during the transaction. Below are the possible values organized by card brand.

Visa Entry Modes

Code	Description
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

Mastercard Entry Modes

Code	Description
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

Elo Entry Modes

Code	Description
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	Contactless interface change
90	Voice authorization
91	Voice Response Unit
92	Batch authorization
93	Batch authorization Cash Access

Electronic Commerce Indicator Values

The electronicCommerceIndicator (ECI) field indicates the security level of an e-commerce transaction. Below are the possible values organized by card brand.

Visa Electronic Commerce Indicators

Code	Description
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

Mastercard Electronic Commerce Indicators

Code	Description
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

Elo Electronic Commerce Indicators

Code	Description
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