# Arquitectura y Flujo de Datos de Tarjeta Presente

Este documento proporciona una visión técnica de la arquitectura **Tarjeta Presente** dentro del Single Entry Point (SEP). Explora cómo los terminales físicos se integran con la Regional API para procesar transacciones seguras en toda América Latina.

## Arquitectura de Alto Nivel

La solución SEP Tarjeta Presente aprovecha la misma infraestructura que el comercio electrónico (Regional API) pero sustituye los datos de la tarjeta introducidos por el cliente por **cargas de datos (payloads) protegidas por hardware**.

### Topologías de Conectividad

| Topología | Ruta del Flujo de Datos | Caso de Uso |
| :--- | :--- | :--- |
| **Integración Directa** | Terminal → Getnet Cloud | POS/mPOS independientes donde el firmware del dispositivo es el cliente de la API. |
| **Merchant Host** | Terminal → Backend del Comercio → Getnet Cloud | Sistemas de venta minorista integrados donde un servidor central gestiona la lógica de negocio y la orquestación de la API. |

## Los Cuatro Pilares Técnicos

La arquitectura se basa en cuatro componentes fundamentales para garantizar la seguridad y el cumplimiento regional:

1. **Identidad del Terminal**: El número único `terminal_number` (anclado en el objeto `terminal`) identifica el origen físico.
2. **Modos de Entrada Seguros**: El `entry_mode` (`chip`, `chip_contactless`, `magnetic_stripe`) dicta la carga de datos necesaria.
3. **Cargas de Datos de Hardware**: Cadenas cifradas **EMV TLV** (para chips) o **Track 2** (para banda magnética) generadas dentro del enclave seguro del hardware.
4. **Seguridad del PIN (DUKPT)**: Cuando se utiliza `online_pin`, el esquema **DUKPT** garantiza que el `pin_block` y el `ksn` (Key Serial Number) se transmitan de forma segura.

## Flujos de Transacción

### Flujo de Un Solo Paso (Venta)

Flujo estándar donde la autorización y la captura ocurren en una única llamada a la API utilizando `DIRECT_CREDIT` o `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
```

### Flujo de Dos Pasos (Preautorización y Captura)

Se utiliza para alquileres u hostelería donde el importe final se confirma más tarde.

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

    Note over App, Issuer: Paso 1: Autorización (Tarjeta 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: Paso 2: Captura (Card Not Present)
    App->>API: POST /v2/payments/capture
    API->>Issuer: Settle Funds
    Issuer-->>API: Confirmed
    API-->>App: Status: CAPTURED
```

### Pago con Código QR (Visa/Mastercard)

Este flujo está disponible para pagos QR de Visa y Mastercard en terminales 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)
```

## Variaciones Regionales

La arquitectura se adapta a los requisitos regionales específicos definidos en la API:

- **Argentina y Chile**: Cuentan con un punto de enlace dinámico de **Cuotas de Pago** (`/v2/payments/quotes`) para obtener planes basados en o BIN de la tarjeta.
- **México**: Utiliza planes de cuotas predefinidos directamente en la solicitud de pago.

## Seguridad y Cumplimiento

- **Liability Shift**: Al utilizar la tecnología EMV (Chip y PIN), la responsabilidad por el fraude se traslada del comercio al emisor.
- **Reducción del Alcance PCI-DSS**: El cifrado de hardware (P2PE/DUKPT) garantiza que los entornos de los comercios nunca manejen datos de tarjetas en texto claro.
- **Cifrado de Extremo a Extremo (E2EE)**: Los datos de la tarjeta se cifran en el punto de interacción (POI) y solo se descifran dentro de los Módulos de Seguridad de Hardware (HSM) seguros de Getnet.

## Ver También

- **[Introducción a Tarjeta Presente](/es/global-api/sep-card-present/first-steps-cp/card-present-intro)**
- **Requisitos del Terminal**
- **Requisitos Regionales**
- **Especificaciones de EMV Tags**