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. Você também precisa do par de chaves RSA gerado e das chaves DUKPT injetadas — consulte Gere e Injete as Chaves de Criptografia — 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:

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]

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

Requisição do Sistema Host (Y19):

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

Resposta do Pinpad (sucesso Contactless):

<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]

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.

/**
 * 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.

/**
 * 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.

/**
 * 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:

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: saiba como configurar transações de compra que incluem saque em dinheiro.
2. Cancelamentos e Estornos: saiba como interromper um comando ativo ou processar o estorno de uma transação.
3. Tratamento de Erros: entenda como interpretar os códigos de relatório Y0E quando uma transação falha.