# Tecnologia EMV no SEP Cartão Presente

**EMV** (Europay, Mastercard e Visa) é o padrão global para pagamentos seguros com cartão de crédito e débito baseado na tecnologia Integrated Circuit Card (ICC). Dentro do ecossistema **Single Entry Point (SEP)**, a Regional API processa essas transações consumindo strings de dados criptografadas por hardware capturadas durante a interação física entre o cartão e o leitor.

A integração da tecnologia EMV garante a proteção de **Liability Shift**, transferindo o risco de chargebacks relacionados a fraude do estabelecimento comercial para o emissor do cartão.

## O Coração do EMV: Dados TLV

Ao contrário das transações de e-commerce que utilizam números de cartão em texto aberto, as transações EMV comunicam-se via formato **TLV (Tag-Length-Value)**. Esta codificação garante que os dados sensíveis do cartão e os criptogramas da transação sejam transmitidos com segurança.

- **Tag**: Um identificador hexadecimal para um elemento de dado específico (ex: `9F02` para Amount, Authorized).
- **Length**: Indica o tamanho do valor em bytes.
- **Value**: A informação real criptografada ou codificada (o payload).

Na Regional API, toda essa coleção de tags é passada como uma única string hexadecimal concatenada no campo **`emv`** dentro do objeto `card`.

## Implementação na Regional API

Para processar uma transação EMV, os desenvolvedores devem mapear os dados capturados pelo hardware para a requisição `POST /v2/payments`. O gateway utiliza os seguintes campos para acionar a lógica de processamento EMV:

| Campo | Requisito | Propósito Técnico |
| --- | --- | --- |
| **`payment_method`** | Obrigatório | Deve usar enums "Direct" (`DIRECT_CREDIT`). |
| **`emv`** | Obrigatório | A string TLV completa coletada do chip do cartão. |
| **`entry_mode`** | Obrigatório | Deve ser definido como `chip` (contato) ou `chip_contactless` (NFC). |
| **`aid`** | Obrigatório | O Identificador de Aplicação (ex: `A0000000031010` para Visa). |

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

O campo **`cardholder_verification_method`** define como a identidade do cliente é confirmada durante a transação:

* **`online_pin`**: O PIN é criptografado pelo hardware e enviado ao emissor para validação em tempo real.
* **`offline_pin`**: O PIN é validado localmente pelo chip do cartão.
* **`signature`**: O cliente fornece uma assinatura física ou digital.
* **`no_cvm`**: A verificação é ignorada (comum em pagamentos por aproximação de baixo valor).

## Segurança e Validação de PIN Online

Para transações que exigem **Online PIN**, a API utiliza o sistema de gerenciamento **DUKPT** (Derived Unique Key Per Transaction) para garantir a conformidade PCI.

### Objetos de PIN Obrigatórios

Quando o `cardholder_verification_method` é definido como `online_pin`, os seguintes campos tornam-se obrigatórios:

1. **`pin_block`**: Um payload de PIN criptografado formatado em ISO-9564.
2. **`ksn` (Key Serial Number)**: Uma string hexadecimal de 20 dígitos usada pelo gateway para identificar a chave de decifração.

### Contexto do Service Code

A API também avalia flags especializadas para confirmar a natureza física do cartão:

* **`chip`**: Definido como `true` para confirmar a presença de um chip físico.
* **`pin_required`**: Informa ao gateway se o PIN era obrigatório para aquele cartão específico.

## Leia Mais

Para continuar sua integração, explore estes guias técnicos relacionados:

- **[Visão Geral do Cartão Presente]()**: Entenda a arquitetura unificada SEP e a disponibilidade regional.
- **[Modos de Entrada do Cartão]()**: Detalhamento dos payloads de `chip`, `chip_contactless` e `magnetic_stripe`.
- **[Pagamentos de Passo Único]()**: Saiba como realizar transações imediatas de venda e captura.
- **[Pagamentos Pré-autorizados]()**: Implemente o fluxo de dois passos para reservas e capturas posteriores.