chargeback-docs

Enriquecimiento de Transacción

Enriquecimiento de Datos

Le enviaremos una notificación webhook (HTTP POST) en el siguiente formato:

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

Campos de la Notificación Webhook

Campo Tipo Requerido Descripción
event string Sí Identificador del tipo de evento. Siempre “transaction” para solicitudes de enriquecimiento de transacción
payload object Sí Contenedor para los datos de identificación de la transacción
payload.contractDisputeId string Sí Identificador único interno de Tupi para el contrato de disputa
payload.transactionIdentifier string No ID de Transacción (TID). Puede ser null dependiendo de la marca de tarjeta
payload.acquirerReferenceNumber string No Número de Referencia del Adquirente (ARN). Puede ser null dependiendo de la marca de tarjeta

Importante: El transactionIdentifier (TID) o acquirerReferenceNumber (ARN) siempre será proporcionado, aunque uno de ellos puede ser null dependiendo de la marca de tarjeta. Debe usar el identificador que esté disponible para buscar la transacción en su sistema.

Luego debe enviarnos una solicitud HTTP POST a la URL de callback proporcionada durante la configuración (contáctenos si no está seguro de qué endpoint usar).

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

        // consejo: igual que enviado por la marca
        "entryMode": "5",
        "electronicCommerceIndicator": "05", // ECI

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

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

Campos de la Solicitud de Callback

Campo Tipo Requerido Descripción
type string Sí Identificador del tipo de solicitud. Siempre “transaction” para datos de transacción
data object Sí Contenedor para los datos de la transacción
data.authorizationCode string Sí Código de autorización de la transacción
data.authorizationStatusCode string No Código de estado de la autorización (ej: “00” para aprobado)
data.authorizationCurrencyCode string Sí Código de moneda en formato ISO 4217 (ej: “986” para BRL)
data.authorizationSystemTraceAuditNumber string Sí STAN o NSU de autorización
data.authorizationDate string Sí Fecha y hora de autorización en formato ISO 8601
data.authorizationAmount number Sí Monto de autorización en centavos (ej: 10000 = 100.00)
data.acquirerReferenceNumber string Sí Número de Referencia del Adquirente (ARN)
data.transactionIdentifier string No ID de Transacción (TID)
data.terminalIdentifier string No Identificador del terminal donde ocurrió la transacción
data.cardNumber string Sí Número de tarjeta enmascarado (primeros 6 y últimos 4 dígitos visibles)
data.paymentPlan number Sí Identificador del plan de pago
data.entryMode string Sí Modo de entrada de tarjeta (igual que enviado por la marca de tarjeta)
data.electronicCommerceIndicator string Sí Indicador de Comercio Electrónico (ECI)
data.installments array Sí Array de objetos de cuotas de la transacción
data.vouchers array No Array de objetos de vouchers de la transacción

Campos del Objeto Installment

Campo Tipo Requerido Descripción
acquirerReferenceNumber string Sí ARN para esta cuota específica
installmentNumber number Sí Número secuencial de la cuota
installmentDate string Sí Fecha de la cuota en formato ISO 8601
amount number Sí Monto de la cuota en centavos
issuerSettlementStatus string Sí Estado de liquidación con el emisor. Valores: “settled”, “scheduled”, “canceled”, “confirmed”, “sent”
merchantSettlementStatus string Sí Estado de liquidación con el comerciante. Valores: “settled”, “scheduled”, “canceled”

Campos del Objeto Voucher

Campo Tipo Requerido Descripción
acquirerReferenceNumber string Sí ARN para este voucher específico
amount number Sí Monto del voucher en centavos
voucherDate string Sí Fecha del voucher en formato ISO 8601
installmentNumber number Sí Número de cuota asociada

Valores de Entry Mode

El campo entryMode indica cómo se capturó la información de la tarjeta durante la transacción. A continuación se presentan los valores posibles organizados por marca de tarjeta.

Modos de Entrada Visa

Código Descripción
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 Descripción
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 Descripción
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 Cambio de interfaz Contactless
90 Voice authorization
91 Voice Response Unit
92 Batch authorization
93 Batch authorization Cash Access

Valores de Indicador de Comercio Electrónico

El campo electronicCommerceIndicator (ECI) indica el nivel de seguridad de una transacción de comercio electrónico. A continuación se presentan los valores posibles organizados por marca de tarjeta.

Indicadores de Comercio Electrónico Visa

Código Descripción
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 Comercio Electrónico Mastercard

Código Descripción
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 Comercio Electrónico Elo

Código Descripción
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