# Requisitos do Terminal para Cartão Presente

Este documento de referência descreve os requisitos técnicos para integrar um terminal de hardware físico à **Getnet Regional API** para transações **Cartão Presente**. Antes de enviar qualquer requisição de pagamento, seu terminal deve atender a essas especificações para garantir o sucesso da autorização e a conformidade.

## Visão Geral

Cada transação Cartão Presente na Regional API está vinculada a um dispositivo físico específico e registrado. O gateway utiliza a identidade do terminal para aplicar políticas de segurança, regras fiscais regionais e permitir a conciliação por dispositivo. Uma requisição que não apresente ou possua uma configuração de terminal inválida será rejeitada.

## Requisitos de Requisição da API

### Cabeçalho Obrigatório

Todas as requisições de pagamento Cartão Presente devem incluir o seguinte cabeçalho HTTP:

| Cabeçalho | Valor | Descrição |
| --- | --- | --- |
| `x-transaction-channel-entry`| `XX` | Identifica a plataforma que está enviando a transação. Este código é atribuído pela Getnet e deve ser solicitado à equipe de Suporte à Integração. |

<Callout type="warning">

Este cabeçalho é obrigatório para todas as transações integradas por hardware.

</Callout>

### Objeto `terminal` Obrigatório

O objeto `terminal` deve ser incluído dentro de `data.payment` em todas as requisições Cartão Presente. Ele identifica o dispositivo físico registrado que está processando a transação.

```json
"data": {
  "payment": {
    "terminal": {
      "terminal_number": "21000334"
    }
  }
}
```

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `terminal_number` | `string` | **Sim** | O identificador exclusivo do terminal físico registrado. Fornecido pela Getnet durante o onboarding do dispositivo. |

<Callout type="note">

O objeto `terminal` é um **objeto obrigatório para Cartão Presente**, conforme definido no esquema da API. Uma requisição sem um `terminal_number` válido será rejeitada.

</Callout>

## Capacidades de Hardware

Seu terminal físico deve suportar as seguintes capacidades para processar transações Cartão Presente por meio da Regional API:

### Modos de Entrada de Cartão

O terminal deve ser capaz de ler pelo menos um dos seguintes modos de entrada, que determina o payload de dados enviado à API:

| Modo de Entrada (`entry_mode`) | Requisito de Hardware | Principal Campo de Dados |
| --- | --- | --- |
| `chip` | Leitor de slot ICC (Integrated Circuit Card) | `emv` (string TLV) |
| `chip_contactless` | Leitor NFC (Near Field Communication) | `emv` (string TLV) |
| `magnetic_stripe` | Leitor de cabeça de tarja magnética | `track_2` |

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

O terminal deve suportar pelo menos um dos seguintes métodos de verificação, que determina os campos de segurança adicionais exigidos na requisição:

| CVM (`cardholder_verification_method`) | Requisito de Hardware | Campos Adicionais Exigidos |
| --- | --- | --- |
| `online_pin` | PIN pad seguro com criptografia DUKPT | `pin_block`, `ksn` |
| `offline_pin` | Verificação local do chip ICC | Nenhum (lidado pelo cartão) |
| `signature` | Tela ou comprovante de papel | Nenhum (estabelecimento armazena a assinatura) |
| `no_cvm` | Nenhum (aproximação de baixo valor) | Nenhum |

### Processamento de Chip EMV

Para os modos de entrada `chip` e `chip_contactless`, o terminal deve:

- **Ler e analisar os dados TLV** do Circuito Integrado (IC) do cartão.
- **Gerar um Application Cryptogram (ARQC)** para cada transação.
- **Concatenar todas as EMV Tags** em uma única string codificada em hex para o campo `emv`.
- **Fornecer o Application Identifier (AID)** no campo `aid`.

### Criptografia de PIN (DUKPT)

Para transações com `online_pin`, o PIN pad do terminal deve:

- **Criptografar o PIN** usando o esquema de gerenciamento **DUKPT (Derived Unique Key Per Transaction)**.
- **Gerar um PIN Block** no formato **ISO 9564-1 Format 0 (ISO-0)**.
- **Fornecer o KSN** (Key Serial Number) — uma string hexadecimal de 20 dígitos — para permitir que o HSM da Getnet derive a chave de decifração correta.

| Campo | Formato | Exemplo |
| --- | --- | --- |
| `pin_block` | String codificada em hex | `A0B6BA8D53C8D3C3` |
| `ksn` | String hex de 20 dígitos | `BC756011020000400001` |

## Requisitos de Conectividade

Seu terminal deve ser capaz de alcançar os endpoints da Getnet Regional API via HTTPS. As seguintes URLs base se aplicam:

| Ambiente | URL Base |
| --- | --- |
| **Sandbox** | `https://api-sbx.pre.globalgetnet.com` |
| **Produção** | `https://api.pre.globalgetnet.com` |

### Topologias de Rede

A Regional API suporta duas topologias principais de integração:

| Topologia | Descrição |
| --- | --- |
| **Integração Direta** | O firmware do terminal atua como o cliente da API, lidando com a autenticação OAuth 2.0 e a construção do JSON diretamente. |
| **Merchant Host** | O terminal captura os dados do hardware (EMV, Track 2, PIN Block) e os encaminha para um servidor de backend do estabelecimento comercial, que então constrói e envia a requisição da API. |

## Registro do Terminal

Antes de processar transações reais, seu terminal deve estar registrado na Getnet. Entre em contato com a equipe de Suporte à Integração para:

1. Obter um `terminal_number` válido para cada dispositivo físico.
2. Solicitar o código `x-transaction-channel-entry` para sua plataforma de integração.
3. Configurar a injeção de chaves DUKPT para terminais habilitados para PIN.

## Resumo de Campos Obrigatórios

A tabela a seguir consolida todos os campos obrigatórios para uma requisição de pagamento Cartão Presente:

| Campo / Cabeçalho | Localização | Obrigatório Para |
| --- | --- | --- |
| `x-transaction-channel-entry: XX` | Cabeçalho HTTP | Todas as transações |
| `data.payment.terminal.terminal_number` | Corpo da Requisição | Todas as transações |
| `data.payment.card.entry_mode` | Corpo da Requisição | Todas as transações |
| `data.payment.card.emv` | Corpo da Requisição | `chip`, `chip_contactless` |
| `data.payment.card.aid` | Corpo da Requisição | `chip`, `chip_contactless` |
| `data.payment.card.track_2` | Corpo da Requisição | `magnetic_stripe` (e muitas vezes `chip`) |
| `data.payment.card.pin_block` | Corpo da Requisição | CVM `online_pin` |
| `data.payment.card.ksn` | Corpo da Requisição | CVM `online_pin` |
| `data.payment.card.seq_number` | Corpo da Requisição | `chip` com `online_pin` |

## Leia Mais

- **Modos de Entrada do Cartão**: Detalhamento de payloads de `chip`, `chip_contactless` e `magnetic_stripe`.
- **Validação de PIN**: Requisitos técnicos para transmissão de `pin_block` e `ksn`.
- **[Especificações de EMV Tags](/pt/global-api/reference-global/emv-tags)**: Referência para todas as tags TLV incluídas no campo `emv`.
- **Guia de Início Rápido**: Crie seu primeiro pagamento Cartão Presente no Sandbox.
- **Pagamentos de Passo Único**: Guia completo para fluxos imediatos de venda e captura.