# maxipago/sdk-java-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/maxipago/sdk-java-v2
- Repository: https://github.com/maxipago/sdk-java-v2

## Overview

##### Project Type and Purpose
- This is a Maven‐based Java SDK (client library) designed to simplify integrations with the MaxiPago payment gateway.
- It abstracts XML generation, HTTP communication, and response parsing for operations like auth, capture, sale (credit/debit), boleto, Pix, 3DS2, antifraud, recurring, customer/card management, etc.

##### File Structure Analysis
- Top‐level pom.xml: Maven project definition.
- src/main/java/com/maxipago: Core package containing:
- Domain models (Customer, Payment, Order, CardInfo, Pix, Wallet, SDWO, etc.)
- Enums (processor IDs, UI types, periods).
- Payment methods subpackage (Card, Boleto, OnlineDebit, Pix, Token).
- Request subpackage (AbstractRequest, Processor, ApiRequest/ApiResponse, TransactionRequest/Response).
- MaxiPago.java: entry point, ties Environment + request builders.
- src/test: Wiremock tests + sample XML responses for contract testing.

##### README Insights
- Lists supported operations (auth, sale, cancel, refund, zero‐dollar, 3DS, SDWO, dynamic MCC, Pix).
- Shows how Environment selects sandbox/production.
- Demonstrates builder-style, chainable API for constructing requests.
- Exposes key response fields and guidance on using responseCode.

##### Core Components
a. Component Identification
1. SDK Layer
– Entry Point: MaxiPago (Environment config)
– Request Builders: auth(), sale(), capture(), cancel(), pix(), etc.
– Domain Models: Customer, Payment, Card, Pix, Wallet, Item, SDWO, Device, Document
– Enums: SdkInterfaceEnum, SDWOProcessingType, etc.
2. Request Processing Layer
– AbstractRequest: common XML‐building logic
– Processor: HTTP transport abstraction
– ApiRequest/ApiResponse & RApiRequest/RApiResponse: mapping between domain and raw HTTP payloads
3. Transport / Serialization Layer
– XML Renderer / Serializer (SaveOnFile, RenderOptions)
– HTTP Client (Java URLConnection or 3rd-party HTTP library)
4. Test Harness
– Wiremock server stub
– Sample XML fixtures
5. External Services
– MaxiPago API endpoints (sandbox | production)
– Optional: Fraud Control, 3DS v2 provider, acquiring banks

b. Relationships & Data Flow
- Developer code calls MaxiPago → selects Environment → calls a request builder (e.g., maxiPago.sale()).
- Builder populates Domain Models → AbstractRequest transforms models into XML.
- Processor sends XML via HTTP to external MaxiPago API → receives XML response.
- ApiResponse parsing → maps back to TransactionResponse (domain).
- Response returned to developer.

c. Architectural Patterns & Principles
- Builder / Fluent API for request construction.
- Template Method in AbstractRequest for common XML building + extension hooks.
- Single Responsibility: separate domain models, request builders, transport logic.
- Testable—HTTP interactions isolated via Processor + Wiremock.
- Configuration abstraction: Environment for sandbox vs. production.

d. Key Technologies & Libraries
- Java 8+; Maven for build and dependency management.
- HTTP client (built‐in or Apache HttpClient).
- XML serialization/parsing (manual or JAXB).
- Wiremock for integration tests.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Developer
    DEV["Developer Code"]:::external

    %% SDK Layer
    subgraph "SDK Layer"
        MP["MaxiPago (Entry Point)"]:::sdk
        ENV["Environment Config"]:::sdk
        RB["Request Builders"]:::sdk
        DM["Domain Models"]:::sdk
        EN["Enums"]:::sdk
        PM["Payment Methods"]:::sdk
    end

    %% Request Processing Layer
    subgraph "Request Processing Layer"
        AR["AbstractRequest"]:::sdk
        PR["Processor"]:::sdk
        APIREQ["ApiRequest/ApiResponse"]:::sdk
        RAPI["RApiRequest/RApiResponse"]:::sdk
        TR["TransactionRequest/Response"]:::sdk
    end

    %% Transport/Serialization Layer
    subgraph "Transport/Serialization Layer"
        XS["XML Serializer\n(RenderOptions/SaveOnFile)"]:::sdk
        HC["HTTP Client"]:::sdk
    end

    %% Test Harness
    subgraph "Test Harness"
        WM["Wiremock Tests"]:::test
        XF["XML Fixtures"]:::test
    end

    %% External API
    EXT["MaxiPago API\n(Sandbox/Production)"]:::external

    %% Build & Docs
    subgraph "Build & Docs"
        POM["Maven POM\n(pom.xml)"]:::sdk
        RD["README.md"]:::sdk
    end

    %% Data Flow
    DEV -->|"calls"| MP
    MP -->|"selects env"| ENV
    MP -->|"invokes"| RB
    RB -->|"populates"| DM
    RB -->|"uses enums"| EN
    RB -->|"uses methods"| PM
    RB -->|"creates request"| AR
    AR -->|"uses"| PR
    PR -->|"builds XML"| XS
    PR -->|"uses raw variants"| RAPI
    XS -->|"produces XML"| HC
    HC -->|"sends HTTP"| EXT
    EXT -->|"returns XML"| HC
    HC -->|"receives XML"| PR
    PR -->|"maps payload"| APIREQ
    APIREQ -->|"maps to domain"| TR
    TR -->|"returns response"| DEV

    %% Test Harness Connections
    WM -->|"stubs HTTP"| PR
    WM -->|"uses fixtures"| XF

    %% Click Events
    click MP "https://github.com/maxipago/sdk-java-v2/blob/master/src/main/java/com/maxipago/MaxiPago.java"
    click ENV "https://github.com/maxipago/sdk-java-v2/blob/master/src/main/java/com/maxipago/Environment.java"
    click DM "https://github.com/maxipago/sdk-java-v2/tree/master/src/main/java/com/maxipago/"
    click EN "https://github.com/maxipago/sdk-java-v2/tree/master/src/main/java/com/maxipago/enums/"
    click PM "https://github.com/maxipago/sdk-java-v2/tree/master/src/main/java/com/maxipago/paymentmethod/"
    click AR "https://github.com/maxipago/sdk-java-v2/blob/master/src/main/java/com/maxipago/request/AbstractRequest.java"
    click PR "https://github.com/maxipago/sdk-java-v2/blob/master/src/main/java/com/maxipago/request/Processor.java"
    click APIREQ "https://github.com/maxipago/sdk-java-v2/tree/master/src/main/java/com/maxipago/request/"
    click RAPI "https://github.com/maxipago/sdk-java-v2/blob/master/src/main/java/com/maxipago/request/RApiRequest.java"
    click TR "https://github.com/maxipago/sdk-java-v2/blob/master/src/main/java/com/maxipago/request/TransactionRequest.java"
    click XS "https://github.com/maxipago/sdk-java-v2/blob/master/src/main/java/com/maxipago/RenderOptions.java"
    click WM "https://github.com/maxipago/sdk-java-v2/blob/master/src/test/java/com/maxipago/MaxiPagoTestWiremock.java"
    click XF "https://github.com/maxipago/sdk-java-v2/tree/master/src/test/resources/"
    click POM "https://github.com/maxipago/sdk-java-v2/blob/master/pom.xml"
    click RD "https://github.com/maxipago/sdk-java-v2/blob/master/README.md"

    %% Styles
    classDef sdk fill:#D0E8FF,stroke:#3399FF,stroke-width:1px;
    classDef external fill:#DFFFE0,stroke:#33CC33,stroke-width:1px;
    classDef test fill:#FFF5CC,stroke:#FFCC00,stroke-width:1px;
```
