# Introdução ao Cartão Presente

Uma transação **Cartão Presente** ocorre quando um pagamento é iniciado por meio de um hardware físico—como um terminal POS, mPOS ou um PIN pad integrado—onde o cartão é lido fisicamente pelo dispositivo.

Diferentemente do e-commerce (Card-Not-Present), onde o usuário digita manualmente os dados do cartão em um navegador, as transações dependem da troca de dados criptografados gerados pelo hardware. No contexto da **Regional API**, isso significa afastar-se de números de cartão em texto aberto e adotar payloads seguros de **EMV (Chip)** e **Tarja Magnética** que utilizam criptografia **DUKPT (Derived Unique Key Per Transaction)**.

## Os Quatro Pilares do Cartão Presente

Para entender como o Single Entry Point (SEP) lida com vendas físicas, você deve dominar estes quatro conceitos fundamentais:

### 1. Identidade do Terminal

Cada transação física deve ser vinculada a uma peça de hardware específica registrada no ecossistema Getnet. Isso é gerenciado pelo objeto **`terminal`**, que exige um **`terminal_number`** exclusivo. Esse ID informa ao gateway exatamente qual dispositivo físico está solicitando a autorização, o que é crítico para a segurança, relatórios fiscais regionais e conciliação específica do terminal.

### 2. Modos de Entrada Seguros

O campo `entry_mode` identifica como os dados do cartão foram capturados, o que determina os requisitos de dados subsequentes no objeto `card`:

- **`chip`**: O cartão foi inserido em um leitor de Integrated Circuit Card (ICC).
- **`magnetic_stripe`**: O cartão foi passado pelo leitor de tarja, exigindo os dados completos do `track_2`.
- **`chip_contactless`**: O cartão ou carteira móvel foi aproximado via Near Field Communication (NFC).

### 3. Métodos de Verificação do Portador (CVM)

A verificação não é mais apenas uma "checagem de CVV". Nos fluxos de Cartão Presente, o **`cardholder_verification_method`** define o aperto de mão (handshake) de segurança:

- **`online_pin`**: Exige o **`pin_block`** criptografado e o **`ksn`** (Key Serial Number) do hardware.
- **`no_cvm`**: Usado para transações de baixo valor ou por aproximação onde o PIN não é exigido.

### 4. O Payload Criptografado

Em vez de enviar dados sensíveis do cartão em texto aberto, seu leitor de hardware gera strings seguras:

- **`emv`**: Uma coleção de tags **Tag-Length-Value (TLV)** capturadas do chip.
- **`track_2`**: O equivalente digital da tarja magnética, muitas vezes exigido mesmo em transações com chip por questões de compatibilidade.

## Topologias de Rede: Como os Dados Chegam à API

A Regional API suporta duas formas principais para a comunicação do seu hardware:

- **Integração Direta**: O terminal conecta-se diretamente aos endpoints de nuvem da Getnet.
- **Merchant Host**: O terminal envia os dados para o seu servidor interno (Host), que então encaminha a requisição para a Regional API.

## Por que Cartão Presente?

O principal motivador para a integração de hardware é o **Liability Shift**. Quando você processa uma transação usando tecnologia **EMV (Chip & PIN)**, a responsabilidade por transações fraudulentas passa do estabelecimento comercial para o emissor do cartão. Como o chip físico e o PIN criptografado são quase impossíveis de clonar, o gateway trata essas transações com o mais alto nível de confiança.