# mercadopago/sdk-dotnet architecture

> Architecture diagram of the GitHub repository mercadopago/sdk-dotnet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mercadopago/sdk-dotnet
- Repository: https://github.com/mercadopago/sdk-dotnet

## Overview

##### Project Type and Purpose
- This is an open-source, language-specific SDK (a .NET client library) for interacting with Mercado Pago’s payment APIs.
- Primary consumers are .NET applications (console apps, web back-ends, desktop apps) that need to call Mercado Pago endpoints.

##### High-Level Components
a. SDK Core (in src/MercadoPago)
- Config: MercadoPagoConfig (holds AccessToken, RetryStrategy, custom HttpClient)
- Client: one Client class per API surface (OrderClient, PaymentClient, etc.)
- Http: DefaultHttpClient, IHttpClient, DefaultRetryStrategy, IRequestOptions
- Serialization: DefaultSerializer, ISerializer, converters
- Error Handling: ApiError, MercadoPagoException
b. Unit Tests (src/MercadoPago.Tests)
- Client unit tests (using mock HttpClient)
- Serialization tests
c. Documentation (docfx configuration + docs/ folder)
- Auto-generated API reference via DocFX
- Static HTML output
d. Examples (examples/ folder)
- Sample .NET console programs demonstrating common flows (Order Create, Capture, Refund, etc.)
e. CI/CD (GitHub workflows)
- CI.yml: runs tests on push/PR
- CD.yml: builds/publishes NuGet package

##### Relationships and Data Flows
- Developer App → references NuGet package → instantiates Client classes
- Client uses Config (AccessToken, HttpClient, RetryStrategy)
- Client calls IHttpClient.SendAsync → HTTP/JSON REST call to Mercado Pago API (external service)
- Response JSON → Serialization layer → Resource models → returned to caller
- Error HTTP codes → mapped to ApiError/MercadoPagoException
- Unit tests mock IHttpClient to verify client logic without real network

##### Architectural Patterns and Principles
- Modular layering: Config → Client → Http → Serialization → Resource
- Dependency inversion: Client depends on IHttpClient & ISerializer interfaces
- Single Responsibility: each Client handles one API domain; Serializer handles only JSON mapping
- Idempotency & retry built into Http layer
- Extensibility: per-request RequestOptions, custom HttpClient injection

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumer Layer
    DeveloperApp["Developer Application"]:::consumer

    %% SDK Core Layer
    subgraph "SDK Core"
        direction TB
        Config["MercadoPagoConfig"]:::core
        subgraph "Client Modules"
            direction TB
            PaymentClient["PaymentClient"]:::core
            OrderClient["OrderClient"]:::core
            AdvancedPaymentClient["AdvancedPaymentClient"]:::core
            RequestOptions["RequestOptions"]:::core
            IdempotentRequest["IdempotentRequest"]:::core
        end
        subgraph "HTTP Layer"
            direction TB
            IHttpClient["IHttpClient"]:::core
            DefaultHttpClient["DefaultHttpClient"]:::core
            IRetryStrategy["IRetryStrategy"]:::core
            DefaultRetryStrategy["DefaultRetryStrategy"]:::core
        end
        subgraph "Serialization"
            direction TB
            ISerializer["ISerializer"]:::core
            DefaultSerializer["DefaultSerializer"]:::core
            DateWithoutHourConverter["DateWithoutHourConverter"]:::core
        end
        subgraph "Resource Models"
            direction TB
            PaymentModel["Payment"]:::core
            OrderModel["Order"]:::core
            AdvancedPaymentModel["AdvancedPayment"]:::core
        end
        subgraph "Error Handling"
            direction TB
            ApiError["ApiError"]:::core
            MercadoPagoException["MercadoPagoException"]:::core
            MercadoPagoApiException["MercadoPagoApiException"]:::core
        end
    end

    %% External API
    ExternalAPI["Mercado Pago REST API"]:::external

    %% Tooling Layer
    subgraph "Tooling & Infrastructure"
        direction TB
        UnitTests["Unit Tests"]:::tooling
        Documentation["DocFX Documentation"]:::tooling
        CI["CI Pipeline"]:::tooling
        CD["CD Pipeline"]:::tooling
    end

    %% Relationships
    DeveloperApp -->|"references NuGet package"| PaymentClient
    DeveloperApp -->|"references NuGet package"| OrderClient
    DeveloperApp -->|"references NuGet package"| AdvancedPaymentClient

    PaymentClient -->|"uses config"| Config
    OrderClient -->|"uses config"| Config
    AdvancedPaymentClient -->|"uses config"| Config

    PaymentClient -->|"calls"| IHttpClient
    OrderClient -->|"calls"| IHttpClient
    AdvancedPaymentClient -->|"calls"| IHttpClient

    Config -->|"injects into"| DefaultHttpClient
    IHttpClient -->|"implemented by"| DefaultHttpClient
    IRetryStrategy -->|"implemented by"| DefaultRetryStrategy
    DefaultHttpClient -->|"uses RetryStrategy"| DefaultRetryStrategy

    DefaultHttpClient -->|"HTTPS/JSON"| ExternalAPI
    ExternalAPI -->|"JSON response"| DefaultHttpClient

    DefaultHttpClient -->|"raw JSON"| DefaultSerializer
    DefaultSerializer -->|"POCOs"| PaymentModel
    DefaultSerializer -->|"POCOs"| OrderModel
    DefaultSerializer -->|"POCOs"| AdvancedPaymentModel

    DefaultHttpClient -->|"error codes"| ApiError
    ApiError -->|"wrapped in"| MercadoPagoApiException
    MercadoPagoApiException -->|"thrown as"| MercadoPagoException
    MercadoPagoException --> PaymentClient
    MercadoPagoException --> OrderClient
    MercadoPagoException --> AdvancedPaymentClient

    %% Tooling connections
    UnitTests -->|"mocks IHttpClient"| PaymentClient
    UnitTests -->|"tests serialization"| DefaultSerializer
    UnitTests -->|"tests HTTP layer"| DefaultHttpClient
    UnitTests -->|"tests config"| Config

    Documentation -->|"generates API reference"| ResourceModels
    CI -->|"runs tests/builds"| UnitTests
    CI -->|"validates"| DeveloperApp
    CD -->|"publishes NuGet"| DeveloperApp

    %% Click Events
    click Config "https://github.com/mercadopago/sdk-dotnet/blob/master/src/MercadoPago/Config/MercadoPagoConfig.cs"
    click PaymentClient "https://github.com/mercadopago/sdk-dotnet/blob/master/src/MercadoPago/Client/Payment/PaymentClient.cs"
    click OrderClient "https://github.com/mercadopago/sdk-dotnet/blob/master/src/MercadoPago/Client/Order/OrderClient.cs"
    click AdvancedPaymentClient "https://github.com/mercadopago/sdk-dotnet/blob/master/src/MercadoPago/Client/AdvancedPayment/AdvancedPaymentClient.cs"
    click RequestOptions "https://github.com/mercadopago/sdk-dotnet/blob/master/src/MercadoPago/Client/RequestOptions.cs"
    click IdempotentRequest "https://github.com/mercadopago/sdk-dotnet/blob/master/src/MercadoPago/Client/IdempotentRequest.cs"
    click IHttpClient "https://github.com/mercadopago/sdk-dotnet/blob/master/src/MercadoPago/Http/IHttpClient.cs"
    click DefaultHttpClient "https://github.com/mercadopago/sdk-dotnet/blob/master/src/MercadoPago/Http/DefaultHttpClient.cs"
    click IRetryStrategy "https://github.com/mercadopago/sdk-dotnet/blob/master/src/MercadoPago/Http/IRetryStrategy.cs"
    click DefaultRetryStrategy "https://github.com/mercadopago/sdk-dotnet/blob/master/src/MercadoPago/Http/DefaultRetryStrategy.cs"
    click ISerializer "https://github.com/mercadopago/sdk-dotnet/blob/master/src/MercadoPago/Serialization/ISerializer.cs"
    click DefaultSerializer "https://github.com/mercadopago/sdk-dotnet/blob/master/src/MercadoPago/Serialization/DefaultSerializer.cs"
    click DateWithoutHourConverter "https://github.com/mercadopago/sdk-dotnet/blob/master/src/MercadoPago/Serialization/DateWithoutHourConverter.cs"
    click PaymentModel "https://github.com/mercadopago/sdk-dotnet/blob/master/src/MercadoPago/Resource/Payment/Payment.cs"
    click OrderModel "https://github.com/mercadopago/sdk-dotnet/blob/master/src/MercadoPago/Resource/Order/Order.cs"
    click AdvancedPaymentModel "https://github.com/mercadopago/sdk-dotnet/blob/master/src/MercadoPago/Resource/AdvancedPayment/AdvancedPayment.cs"
    click ApiError "https://github.com/mercadopago/sdk-dotnet/blob/master/src/MercadoPago/Error/ApiError.cs"
    click MercadoPagoException "https://github.com/mercadopago/sdk-dotnet/blob/master/src/MercadoPago/Error/MercadoPagoException.cs"
    click MercadoPagoApiException "https://github.com/mercadopago/sdk-dotnet/blob/master/src/MercadoPago/Error/MercadoPagoApiException.cs"
    click UnitTests "https://github.com/mercadopago/sdk-dotnet/blob/master/src/MercadoPago.Tests"
    click Documentation "https://github.com/mercadopago/sdk-dotnet/blob/master/docfx.json"
    click CI "https://github.com/mercadopago/sdk-dotnet/blob/master/.github/workflows/CI.yml"
    click CD "https://github.com/mercadopago/sdk-dotnet/blob/master/.github/workflows/CD.yml"

    %% Styles
    classDef consumer fill:#d4f8d4,stroke:#2e7d32,stroke-width:2px;
    classDef core fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef external fill:#ffe0b2,stroke:#e65100,stroke-width:2px;
    classDef tooling fill:#e0e0e0,stroke:#424242,stroke-width:2px;
```
