# Arquitetura e Fluxo de Dados Cartão Presente

Este documento fornece uma visão técnica da arquitetura **Cartão Presente** dentro do Single Entry Point (SEP). Ele explora como os terminais físicos se integram à Regional API para processar transações seguras em toda a América Latina.

## Arquitetura de Alto Nível

A solução SEP Cartão Presente utiliza a mesma infraestrutura do e-commerce (Regional API), mas substitui os dados do cartão inseridos pelo cliente por **payloads protegidos por hardware**.

### Topologias de Conectividade

| Topologia | Caminho do Fluxo de Dados | Caso de Uso |
| :--- | :--- | :--- |
| **Integração Direta** | Terminal → Getnet Cloud | POS/mPOS independente onde o firmware do dispositivo é o cliente da API. |
| **Merchant Host** | Terminal → Backend do Estabelecimento → Getnet Cloud | Sistemas de varejo integrados onde um servidor central gerencia a lógica de negócio e a orquestração da API. |

## Os Quatro Pilares Técnicos

A arquitetura baseia-se em quatro componentes fundamentais para garantir a segurança e a conformidade regional:

1. **Identidade do Terminal**: O `terminal_number` exclusivo (ancorado no objeto `terminal`) identifica a origem física.
2. **Modos de Entrada Seguros**: O `entry_mode` (`chip`, `chip_contactless`, `magnetic_stripe`) dita o payload necessário.
3. **Payloads de Hardware**: Strings criptografadas **EMV TLV** (para chips) ou **Track 2** (para tarja) geradas dentro do enclave seguro do hardware.
4. **Segurança do PIN (DUKPT)**: Quando o `online_pin` é usado, o esquema **DUKPT** garante que o `pin_block` e o `ksn` (Key Serial Number) sejam transmitidos com segurança.

## Fluxos de Transação

### Fluxo de Passo Único (Venda)

Fluxo padrão onde a autorização e a captura ocorrem em uma única chamada de API usando `DIRECT_CREDIT` ou `DIRECT_DEBIT`.

```mermaid
sequenceDiagram
    participant Card as Physical Card
    participant Terminal as Hardware Terminal
    participant App as Client Application
    participant API as Getnet Regional API
    participant Issuer as Card Issuer

    Card->>Terminal: Insert/Tap/Swipe
    Terminal->>Terminal: Encrypt Data (EMV/Track 2/PIN)
    Terminal->>App: Return Secure Payload
    App->>API: POST /v2/payments (Single-Step)
    API->>API: Validate Terminal & Decrypt PIN
    API->>Issuer: Request Authorization
    Issuer-->>API: Approved
    API-->>App: Return payment_id (Status: APPROVED)
    App->>Terminal: Display Result & Print Receipt
```

### Fluxo de Dois Passos (Pré-autorização e Captura)

Usado para aluguéis ou hospitalidade, onde o valor final é confirmado posteriormente.

```mermaid
sequenceDiagram
    participant App as Client Application
    participant API as Getnet Regional API
    participant Issuer as Card Issuer

    Note over App, Issuer: Passo 1: Autorização (Cartão Presente)
    App->>API: POST /v2/payments (DIRECT_CREDIT_AUTHORIZATION)
    API->>Issuer: Hold Funds
    Issuer-->>API: Authorized
    API-->>App: Status: AUTHORIZED (payment_id)

    Note over App, Issuer: Passo 2: Captura (Card Not Present)
    App->>API: POST /v2/payments/capture
    API->>Issuer: Settle Funds
    Issuer-->>API: Confirmed
    API-->>App: Status: CAPTURED
```

### Pagamento via QR Code (Visa/Mastercard)

Este fluxo está disponível para pagamentos via QR Code Visa e Mastercard em terminais físicos.

```mermaid
sequenceDiagram
    participant App as Client Application
    participant API as Getnet Regional API
    participant Wallet as Customer Wallet

    App->>API: POST /v2/payments/qrcode (serial_number, amount)
    API-->>App: 201 Created (qr_code payload)
    App->>App: Render QR on Terminal Screen
    Wallet->>API: Scans & Authorizes
    API-->>App: PAYMENT_APPROVED (Webhook or Status Check)
```

## Variações Regionais

A arquitetura se adapta aos requisitos regionais específicos definidos na API:

- **Argentina e Chile**: Apresentam um endpoint dinâmico de **Cotações de Parcelamento** (`/v2/payments/quotes`) para buscar planos com base no BIN do cartão.
- **México**: Utiliza planos de parcelamento pré-definidos diretamente na requisição de pagamento.

## Segurança e Conformidade

- **Liability Shift**: Ao utilizar a tecnologia EMV (Chip & PIN), a responsabilidade por fraude passa do estabelecimento para o emissor.
- **Redução do Escopo PCI-DSS**: A criptografia de hardware (P2PE/DUKPT) garante que os ambientes dos estabelecimentos comerciais nunca manipulem dados de cartão em texto aberto.
- **End-to-End Encryption**: Os dados do cartão são criptografados no ponto de interação (POI) e decifrados apenas dentro dos Módulos de Segurança de Hardware (HSM) seguros da Getnet.

## Veja Também

- **[Introdução ao Cartão Presente](/pt/global-api/sep-card-present/first-steps-cp/card-present-intro)**
- **Requisitos do Terminal**
- **Requisitos Regionais**
- **Especificações de EMV Tags**