chargeback-docs

📋 Chargeback System Documentation

Status Version Documentation

📚 Complete documentation for APIs and notifications of the chargeback management system

🌐 Language Versions

🎯 Overview

This repository contains the complete technical documentation of the chargeback system, including API specifications, notification formats, and data flows for integration with external systems.

File Ingestion

📁 Documentation Structure

🔄 1. Enrichment (Data Enrichment)

Data Enrichment

Note: The highlighted area represents components that must be developed by the client. This includes implementing the logic to retrieve internal data and sending the responses to our system during the enrichment flow.

Documentation of data enrichment flow between system and client:

File Description Data Flow
1.TRANSACTION.md 💳 Transaction Data
📤 TransactionEvent: Sent to client
📥 TransactionResponse: Received via API		 Event → Client
Response ← Client
2.MERCHANT.md 🏪 Merchant Data
📤 MerchantEvent: Sent to client
📥 MerchantResponse: Received via API		 Event → Client
Response ← Client

📢 2. Notifications (System Notifications)

System Notifications

Documentation of status and lifecycle notifications for chargebacks:

File Description Event Type
3.STATUS.md 📊 Status Notifications - Chargeback process status updates status
4.CYCLE.md 🔄 Cycle Notifications - Cycle changes (chargeback, pre-arbitration, arbitration) cycle

🤖 3. AI (Artificial Intelligence)

AI Recommendation

Documentation of AI agent integration for chargeback recommendations:

File Description Data Type
5.AI.md 🧠 AI Agent Data - Input data sent to the chargeback recommendation AI agent Input API

📋 Available Communication Types

🔄 Data Enrichment (Events ↔ Responses)

Type We Send (Event) We Receive (Response) Documentation
transaction Request transaction data Complete transaction data TRANSACTION.md
merchant Request merchant data Complete merchant data MERCHANT.md

📢 Unidirectional Notifications (Events)

Type We Send (Event) Purpose Documentation
status Status update Inform status changes STATUS.md
cycle Cycle change Inform cycle alterations CYCLE.md

🔧 Integration

📤📥 Communication Flow

The system uses two types of communication:

📤 Events - Sent by System

Notifications that we send to the client when we need additional data:

📥 Responses - Received via API

Complete data that we receive from the client via API to update our system:

Base Event Structure

All sent events follow a common base structure:

type BaseEvent = {
    event: string;
    payload: {
        contractDisputeId: string;
        // ... specific identifiers per event type
    };
}

Base Response Structure

Responses received via API contain complete data:

type BaseResponse = {
    // Complete and detailed data of the requested object
    // Structure varies according to data type
}

Main Identifiers

⚙️ Minimum Requirements

To run the chargeback system, ensure your environment meets the following minimum requirements:

🖥️ Hardware Requirements

🗄️ Database Requirements

☸️ Kubernetes Requirements

📊 Reports and BI Requirements

🔒 Security Requirements

📞 Support

For questions or suggestions about this documentation, contact the development team.

**📄 Documentation maintained by Tupi Fintech team** *Last update: February 2026*