# Validação de PIN

No ecossistema **Cartão Presente**, o Número de Identificação Pessoal (PIN) serve como o **Método de Verificação do Portador (CVM)** mais seguro. Diferente do CVV estático usado no e-commerce, uma interação de PIN envolve um aperto de mão (handshake) criptográfico sofisticado entre o terminal de hardware, o chip do cartão e o sistema de autorização do emissor para garantir que dados sensíveis nunca sejam transmitidos em "texto aberto".

## Validação de PIN Online vs. Offline

A **Regional API** suporta dois métodos distintos para validar o PIN de um cliente, determinados pela configuração do cartão e pelas capacidades do terminal.

### Validação de PIN Offline

O PIN é validado localmente pelo chip seguro no próprio cartão.

- **Processo**: O cliente insere seu PIN no terminal, e o terminal o envia diretamente para o Circuito Integrado (IC) do cartão para comparação.
- **Benefício**: Permite a verificação mesmo se o terminal estiver temporariamente offline ou em um ambiente de baixa conectividade.
- **Impacto na API**: Na sua requisição, `cardholder_verification_method` é definido como `offline_pin` e, como a verificação ocorreu localmente, o `pin_block` normalmente não é enviado ao gateway.

### Validação de PIN Online

O PIN é criptografado pelo hardware e enviado ao emissor do cartão para verificação em tempo real.

- **Processo**: O terminal criptografa o PIN usando uma chave de transação exclusiva e o empacota em um **PIN Block**.
- **Segurança**: Utiliza **DUKPT** (Derived Unique Key Per Transaction) para garantir que, mesmo se a chave de uma transação for comprometida, todas as outras transações permaneçam seguras.
- **Impacto na API**: Este método exige a transmissão tanto do **`pin_block`** quanto do **`ksn`** (Key Serial Number) no payload da API.

## Os Componentes do PIN Online Seguro

Ao implementar o **PIN Online**, sua integração de hardware deve fornecer três elementos criptográficos críticos para a Regional API:

### PIN Block

Uma estrutura de dados segura e criptografada (normalmente 8 bytes para TDES ou 16 bytes for AES) que transporta o PIN. A maioria das implementações utiliza o **ISO 9564-1 Format 0** (ISO-0), que realiza um XOR do PIN do cliente com os últimos 12 dígitos do número do cartão (PAN) para garantir que o bloco resultante seja exclusivo para aquele cartão específico.

### KSN (Key Serial Number)

Um identificador hexadecimal de 20 dígitos que atua como o "mapa" para o gateway decifrar o PIN. Ele é composto por um ID de chave base, um identificador de dispositivo e um contador de transações.

- **Função**: O KSN permite que o HSM (Hardware Security Module) da Getnet derive a **Working Key** exata usada pelo terminal para aquela transação específica.

### Criptografia DUKPT

O esquema de gerenciamento **Derived Unique Key Per Transaction** (DUKPT) garante que o terminal gere uma nova chave de criptografia, não reutilizável, para cada leitura de cartão. Isso evita "ataques de repetição" (replay attacks) e garante a segurança de ponta a ponta, desde o PIN pad físico até o gateway da Getnet.

## Mapeamento Técnico na Regional API

Para qualquer transação onde `cardholder_verification_method` for definido como `online_pin`, os seguintes campos no objeto `card` são obrigatórios:

```json
"card": {
  "entry_mode": "chip",
  "cardholder_verification_method": "online_pin",
  "pin_block": "A0B6BA8D53C8D3C3",
  "ksn": "BC756011020000400001",
  "emv": "9f2701809f3303e0f8c8950580000080..."
}
```

| Campo | Requisito | Descrição |
| --- | --- | --- |
| **`cardholder_verification_method`** | Obrigatório | Definido como `online_pin`. |
| **`pin_block`** | Obrigatório | Os dados do PIN criptografados em hexadecimal. |
| **`ksn`** | Obrigatório | O número de série da chave de 20 dígitos em hexadecimal. |

## Leia Mais

- **Modos de Entrada do Cartão**: Entenda a diferença entre payloads de `chip`, `chip_contactless` e `magnetic_stripe`.
- **[Visão Geral da Tecnologia EMV](/pt/global-api/sep-card-present/core-concepts-cp/emv-technology)**: Aprofundamento em tags TLV e criptogramas de chip.
- **Pagamentos de Passo Único**: Saiba como executar uma venda completa com verificação de PIN.