# Processar pagamentos com cartão

Este guia apresenta um passo a passo técnico detalhado para implementar fluxos de pagamento com cartão — Contactless, Chip e Tarja Magnética — com a solução Pinpad Getnet.

## Como funciona

A integração segue dois caminhos sequenciais principais, conforme a tecnologia detectada na apresentação do cartão:

1. **Fluxo Simplificado (Contactless):** A transação é concluída em uma única troca de comandos (**Y19**).
2. **Fluxo Sequencial (Chip e Tarja Magnética):** Exige uma série de trocas de comandos (**Y19, Y02, Y03**) para capturar dados sensíveis e processar as respostas do emissor.

## Antes de começar

O terminal precisa estar conectado e respondendo ao teste de eco `Y0I`, como descrito em [Configuração e Conectividade](https://docs.globalgetnet.com/pt/products/in-store-payments/host-to-host?doc=h2h-configuration-and-connectivity\&section=qhv6nzspm4fa7zajc43yr3ka). Você também precisa do par de chaves RSA gerado e das chaves DUKPT injetadas — consulte [Gere e Injete as Chaves de Criptografia](https://docs.globalgetnet.com/pt/products/in-store-payments/host-to-host?doc=h2h-generate-and-inject-keys) — porque o `Y19` transporta o módulo e o expoente RSA.

## Passo 1: Inicialize a transação

O Sistema Host usa o comando **Y19** para "acordar" o Pinpad e solicitar a inserção do cartão. Ele contém as informações mínimas necessárias para iniciar uma transação, incluindo valores e chaves de criptografia.

### Payload da requisição Y19 [Host]

A tabela a seguir define os campos obrigatórios da requisição Y19:

| Campo | Atributo | Descrição |
| --- | --- | --- |
| **[CID]** | 3 ANS | Identificador do comando: **“Y19”**. |
| **[RSA]** | 256..512 ANS | Módulo RSA público para criptografar trilhas sensíveis. |
| **[EXP]** | 1..12 ANS | Expoente público RSA. |
| **[TEC]** | 3 N | Tempo limite do comando em segundos ("000" a "999"). |
| **[PMK]** | 1 AN | Posição da MK (Slot 3 para DUKPT); use "N" se nenhum PIN for solicitado. |
| **[WRK]** | 1..16 ANS | Status da WorkingKey; use "N" se não se aplicar. |
| **[IMP]** | 12 N | **Valor da Transação**: numérico de 12 dígitos (ex: \$1.99 = `000000000199`). |
| **[ICB]** | 12 N | **Valor do Cashback**: numérico de 12 dígitos (defina como `0` se não for usado). |
| **[TTY]** | 2 N | **Tipo de Transação**: `00` para Compra, `20` para Estorno. |

> **Billing Descriptor:** Em todas as operações Host-to-Host, o campo `billing_descriptor` da API deve permanecer vazio.

### Comportamento do terminal e UI

Depois de validar a requisição Y19, o terminal passa para a tela de apresentação do cartão.

Como mostra a lógica de implementação acima, o terminal atualiza seu estado interno para `WAITING_CARD` e exibe a mensagem `request_card_msg` configurada.

## Passo 2: Implemente o fluxo contactless (CTLSS)

Em transações Contactless (NFC), o processo é mais direto. O terminal executa as etapas EMV automaticamente e retorna uma resposta final com todos os dados de autorização necessários. O fluxo no Pinpad termina imediatamente após essa resposta.

### Resposta Y19 - modo contactless [Pinpad]

| Campo | Atributo | Descrição |
| --- | --- | --- |
| **[CID]** | 3 ANS | Identificador do comando: **“Y19”**. |
| **[TJA]** | 1..19 N | PAN mascarado (ex: `52874560****4005`). |
| **[MDI]** | 1 A | Modo de entrada: **"L"** (Contactless). |
| **[TC2]** | 256..512 ANS | Dados da Trilha II criptografados com RSA. |
| **[CPG]** | 1..300 ANS | Criptograma EMV (ARQC/TC) para autorização. |
| **[APN]** | 0..32 ANS | Nome da aplicação (ex: "VISA CLASSIC"). |
| **[AID]** | 0..16 ANS | Identificador de aplicação (AID) selecionado. |
| **[PIN]** | 16..32 ANS | PINblock criptografado com DUKPT (se aplicável). |
| **[KSN]** | 20 N | Key Serial Number para descriptografar o PIN. |

Este exemplo mostra a comunicação serial bruta de uma transação Visa Contactless bem-sucedida.

**Requisição do Sistema Host (Y19):**

```text
<STX>Y199BAE56E243A19FA882F7499824DAF558BA710B749E57E60AFF69FF5562C444C08144D2B5E361731AE06D9D1C43E7B6D0E401D04867CC470B524767838843DEB40330CA99D20F99DB6E5B882C696976C522A15855A9BBB5D156BE6BC49CA40759B37ECD57580BD7B6CB473CC2B95DA4558DCB1850D0693AD216BC7B9954B86AEC0FC45CFB954D0F1587C215FCE57FEC91B544DA17C2E9633F0EFA3A262AAB7D7A05D85F9D3753A94CD281DB6766EDB0D61FE8781773A4228215932D49F522E829622A519E6DEFC80C3A2B967AFDCEE77F69302DC90044FD39D99FBE80CB245A768160FA38A80A32D42B86361514E02685387B096A4D0B92D57EE024C38E26BEFF<FS>10001<FS>10500100000000000000000000000412399000000000000001<ETX>{LRC}

```

**Resposta do Pinpad (sucesso Contactless):**

```text
<ACK><STX>Y1945079900****1026<FS>201000PAYWAVE/VISA<FS>000041L1.9.7.1-dev<FS>250350780fca98e5d7768aa626e040ab60b019e57ec812b6127b48144ffa430274a6e6784db873bc758eb73fcc278241f5fcef095303b266a41005984c686f228f23685964e5c2737352e86e275d43c2922d4029f1986513d724021673b7d20e56a4bafb5fc7fad3210b095dc6df243a8f24b8d53dce5ca1285c0d928bb7ef067e0e0840cef0d2cd22040b1e70269a320958dc7e0a2d8d7a74bca2e12c9d4ac53502a604f990640479d9a65095de5a38f907219dcccba49d9104a10828b425d692f6b28bcf42130dc0d24bfb7dc1931c86748dfd65db0557af796b9b6f72fefd01583c8e0e729f04794fdcb91a4066ee7ae8278f015146af286768a80e089dd09343<FS>1NDB900008014<FS>9f370466f228639f36020475950500000000009a032505069c01009f02060000004123999f0306000000000000820220009f3303e0f8c89f1e0838353130494343008407a00000000310109f1a0200325f2a0200325f3401009f2701809f260874bbfcfa90874f229f100706010a03a02808<FS>000005649534120434C4153534943<FS>A0000000031010<FS>N<ETX>{LRC}

```

## Passo 3: Implemente o fluxo de chip e tarja magnética

Se o cartão for inserido (**CHIP**) ou passado (**BANDA**), o terminal retorna uma resposta Y19 intermediária e aguarda novas instruções pelo comando **Y02**.

> **Planos de Parcelamento (Cuotas):** Se um plano identifica as parcelas por um modelo específico (por exemplo, 11 parcelas que representam um "Plan Emisor 6 parcelas"), o Sistema Host deve converter esses valores antes de enviar a requisição para a Getnet.

### Resposta Y19 - modo BANDA/CHIP [Pinpad]

| Campo | Atributo | Descrição |
| --- | --- | --- |
| **[CID]** | 3 ANS | Identificador do comando: **“Y19”**. |
| **[TJA]** | 1..19 N | PAN mascarado. |
| **[CSE]** | 3 N | Código de serviço da Trilha II. |
| **[NYA]** | 1..26 ANS | Nome do portador do cartão (se disponível). |
| **[MDI]** | 1 A | Modo: **"C"** (Chip) ou **"B"** (Banda). |

### Comandos subsequentes

1. **Solicitar dados adicionais (Y02):** O Sistema Host envia este comando para acionar o teclado seguro de digitação do PIN ou para obter as trilhas criptografadas.
2. **Processar resposta do emissor (Y03 - apenas chip):** Após a autorização online, envie a resposta do emissor (código de autorização, código de resposta e scripts do emissor) de volta ao Pinpad para executar o "Second Generate AC".

## Referência de implementação

Para ajudar sua equipe de desenvolvimento a entender a máquina de estados interna do terminal, veja a lógica funcional que o Pinpad usa durante uma transação.

### CommandY19: definição da classe

Esta classe representa o comando de inicialização usado em transações contactless, chip ou tarja magnética.

```kotlin
/**
 * This class represents the Y19 command used in contactless, contact chip, or magnetic stripe transactions.
 * * The Y19 command serves multiple purposes:
 * - It wakes up the payment processor (PP) and requests the user to insert the card.
 * - It returns relevant information to the cashier, including the card number (masking the middle part),
 * the Service Code, and the Bank Code.
 * - It sends the base amount and cashback amount, enabling EMV CTLSS reading without a second card tap.
 * - For chip or magnetic stripe, the flow continues with predefined commands (Y02).
 */
class CommandY19(rawCmd: String?) : Command()

```

### handleCommandY19: ponto de entrada da transação

Esta função privada é o manipulador principal da lógica do comando `Y19`.

```kotlin
/**
 * Handles the Y19 command, "Init transaction".
 * This function:
 * - Implements a state machine to handle the Y19 command.
 * - Is the entry point for all EMV or magnetic stripe transactions.
 * - Requests the card entry.
 * - If CTLSS, the message is responded to and the transaction is completed.
 * - If magnetic stripe or EMV Contact, the terminal waits for the Y02 command.
 */
private fun handleCommandY19(inCmd: String?)

```

### Gerenciamento de estado da UI: setWaitingCardUIState

Quando o Pinpad recebe um `Y19` válido, ele deve mudar a UI para o estado de "espera". A lógica a seguir mostra como o terminal exibe os valores e as solicitações de cashback.

```kotlin
/**
 * Updates the UI state to indicate that the system is waiting for a card to be presented.
 */
fun setWaitingCardUIState(
    currencySymbol: String,
    amount: String,
    isCashback: Boolean = false,
    cashbackAmount: String = "",
    totalAmount: String = ""
) {
    Log.d(TAG, "setWaitingCardUIState")
    viewModel._state.value = viewModel._state.value.copy(
        messageTitle = viewModel.context.getString(R.string.request_card_msg),
        messageAmount = currencySymbol + amount,
        transactionState = TransactionState.WAITING_CARD,
    )
    
    if (isCashback) {
        setIsCashbackState(true)
        viewModel._state.value = viewModel._state.value.copy(
            cashbackAmount = currencySymbol + cashbackAmount,
            totalAmount = currencySymbol + totalAmount
        )
    }
    // Prevent the screen from sleeping during card entry
    DeviceHandler.setScreenOffTimeout(SCREEN_TIMEOUT_NO_SLEEP)
}

```

## Sequência de comandos por tecnologia

A tabela a seguir compara a ordem dos comandos com a tecnologia usada:

| Operação | 1º comando | 2º comando | 3º comando | 4º comando |
| --- | --- | --- | --- | --- |
| **Contactless** | **Y19** (Final) | — | — | — |
| **Chip** | **Y19** (Inicial) | **Y15** (Opcional) | **Y02** (Dados) | **Y03** (Autorização) |
| **Banda** | **Y19** (Inicial) | **Y02** (Dados) | — | — |

## Próximos passos

Depois de implementar os fluxos de pagamento, garanta que seu sistema trate os cenários operacionais e os erros:

1. [**Operações de Cashback**](https://docs.globalgetnet.com/pt/products/in-store-payments/host-to-host?doc=h2h-process-cashback-operations&section=kei2fli2gqggbwgaddtl3xb7): saiba como configurar transações de compra que incluem saque em dinheiro.
2. [**Cancelamentos e Estornos**](https://docs.globalgetnet.com/pt/products/in-store-payments/host-to-host?doc=h2h-cancellations-and-refunds&section=kei2fli2gqggbwgaddtl3xb7): saiba como interromper um comando ativo ou processar o estorno de uma transação.
3. [**Tratamento de Erros**](https://docs.globalgetnet.com/pt/products/in-store-payments/host-to-host?doc=h2h-error-handling&section=kei2fli2gqggbwgaddtl3xb7): entenda como interpretar os códigos de relatório Y0E quando uma transação falha.