Getnet DocsGetnet Docs

Arquitectura y Flujo de Datos de Tarjeta Presente

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page
Connect to CursorUse these docs in CursorConnect to VS CodeUse these docs in VS Code

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íaRuta del Flujo de DatosCaso de Uso
Integración DirectaTerminal → Getnet CloudPOS/mPOS independientes donde el firmware del dispositivo es el cliente de la API.
Merchant HostTerminal → Backend del Comercio → Getnet CloudSistemas 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.

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.

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.

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