# Integração Cartão Presente

A solução **Cartão Presente** dentro da **Global API (SEP)** permite processar transações com cartão físico—incluindo inserção de chip (EMV), por aproximação (NFC) e tarja magnética (MSR)—utilizando hardware seguro integrado diretamente ao nosso ecossistema.

Ao utilizar a mesma infraestrutura de API da nossa solução de Ecommerce, mas alterando para strings de dados protegidas por hardware (EMV Tags e dados de trilha), você obtém uma experiência de conciliação verdadeiramente **omnichannel**. Esta integração transfere o ônus da segurança do seu software para o hardware e para o emissor, aproveitando as proteções de **Liability Shift**.

## A Arquitetura Unificada da Global API

O fluxo de Cartão Presente é um componente central da **Global API**. Ele compartilha as mesmas URLs base, mecanismos de autenticação (OAuth 2.0) e estruturas JSON principais dos pagamentos digitais. A principal diferença reside no payload: você substitui os detalhes do cartão inseridos pelo cliente por dados criptografados gerados pelo hardware.

### Pilares Técnicos Principais

Para integrar o Cartão Presente com sucesso, você deve implementar o seguinte:

- **Identidade do Terminal**: Inclua o `terminal_number` dentro do objeto `terminal` em cada requisição para identificar o dispositivo físico específico registrado.
- **Payloads Gerados por Hardware**: Forneça strings criptografadas **EMV (TLV)**, dados de **Track 2** ou **PIN Blocks** em vez de Primary Account Numbers (PAN) em texto aberto.
- **Métodos de Pagamento Diretos**: Use enums específicos, como `DIRECT_CREDIT`, para acionar a lógica de processamento específica do hardware.
- **Criptografia DUKPT**: Utilize **Derived Unique Key Per Transaction (DUKPT)** para pagamentos verificados por PIN. Você deve transmitir tanto o `pin_block` quanto o `ksn` (Key Serial Number) fornecidos pelo leitor de hardware.

## Topologias de Conectividade

Escolha sua estratégia de integração com base em como seu hardware se comunica com a Global API:

| Topologia | Caminho de Conectividade | Responsabilidade Primária |
| :--- | :--- | :--- |
| **Integração Direta** | Terminal → Getnet API | O firmware do terminal atua como o cliente da API, gerenciando tokens OAuth e a construção do JSON diretamente. |
| **Merchant Host** | Terminal → Servidor do Estabelecimento → Getnet API | O terminal captura os dados brutos; seu servidor de backend gerencia a requisição da API, a lógica de negócio e os cabeçalhos de segurança. |

## Modelos de Transação Principais

A API de Cartão Presente suporta três fluxos de negócios principais para cobrir todos os cenários de varejo e serviços:

1. **Passo Único (Venda)**: Execute uma transação direta onde a autorização e a captura ocorrem simultaneamente.
2. **Dois Passos (Pré-autorização)**: Reserve fundos em um cartão físico (ex: durante o check-in em hotéis ou aluguel de veículos) e realize a captura do valor posteriormente por meio de uma chamada de API separada.
3. **Parcelamento**: Divida o total da compra em múltiplos pagamentos. Escolha entre planos financiados pelo estabelecimento (`INSTALL_NO_INTEREST`) ou financiados pelo emissor (`INSTALL_WITH_INTEREST`).

## Disponibilidade Global e Funcionalidades

As funcionalidades de Cartão Presente estão disponíveis em toda a nossa presença global, suportando requisitos locais como **Chile (CLP)**, **México (MXN)** e **Argentina (ARS)**.

| Funcionalidade | Argentina 🇦🇷 | Chile 🇨🇱 | Brasil 🇧🇷 | México 🇲🇽 |
| :--- | :---: | :---: | :---: | :---: |
| **Chip + PIN** | ✅ | ✅ | ✅ | ✅ |
| **Contactless (NFC)** | ✅ | ✅ | ✅ | ✅ |
| **Tarja Magnética** | ✅ | ✅ | ✅ | ✅ |
| **Parcelamento** | ✅ | ✅ | ✅ | ✅ |

## Segurança e Conformidade

A integração via Cartão Presente reduz significativamente o seu escopo PCI-DSS através de criptografia em nível de hardware:

* **Liability Shift**: Proteja seu negócio contra chargebacks relacionados a fraude processando via interfaces EMV Chip ou Contactless.
* **End-to-End Encryption (E2EE)**: Garante que os dados sensíveis do cartão sejam criptografados dentro do leitor de hardware antes de chegarem à sua rede ou à nossa API.
* **Redução do Escopo PCI-DSS**: Evite processar dados de cartão abertos em seus servidores. Como o hardware lida com a criptografia, seu ônus de conformidade é minimizado.

## Próximos Passos

* **Cartão Presente Quickstart**: Execute seu primeiro pagamento com cartão físico no ambiente de Sandbox.
* **Requisitos do Terminal**: Revise as especificações de hardware e os requisitos de configuração da API.
* **Requisitos Regionais**: Explore moedas específicas de cada país, planos de parcelamento e regulamentações locais.