Comandos da API

Esta referência define a estrutura de baixo nível dos pacotes de comunicação e as sequências operacionais necessárias para interagir com o Pinpad Getnet.

Enquadramento de mensagens e protocolo

Cada mensagem transmitida pela interface serial segue um protocolo de enquadramento rigoroso, com caracteres de controle ASCII para garantir a integridade dos dados.

Estrutura geral do quadro

Todos os pacotes devem seguir o seguinte formato: <STX> [PAYLOAD] <ETX> {LRC}

Componente	Valor Hex	Descrição
`<STX>`	`02h`	Start of Text: indica o início de um quadro de mensagem.
[PAYLOAD]	Variável	O comando em si e seus parâmetros.
`<ETX>`	`03h`	End of Text: indica o fim do payload da mensagem.
{LRC}	Variável	Caractere de verificação: byte de Longitudinal Redundancy Check.

Delimitadores internos do payload

Dentro da seção [PAYLOAD], vários parâmetros são separados pelo caractere Separador de Arquivos (<FS>) (1Ch).

Matriz operacional de comandos

Esta matriz mapeia operações lógicas específicas para a sequência de comandos necessária entre o Sistema Host e o Pinpad.

Operação	Configuração	Ação	Captura de dados	Finalização
Pagamento padrão	`Y19`	`Y15`	`Y02` (Auto PP)	`Y03`
Cashback	`Y19` (TTY 09)	`Y15`	`Y02` (Auto PP)	`Y03`
Estorno	`Y19` (TTY 20)	—	`Y02` (Auto PP)	`Y03`
Pagamento QR	—	`Y0Q`	—	`Y0Q` (Limpar)
Echo Test	—	`Y0I`	—	—
Atualização (YDL)	`YDL` (Init)	`YDL` (Data)	—	`YDL` (End)

Definições principais de payload

Cada campo abaixo é separado por <FS> (1Ch) e enquadrado por <STX>/<ETX>/{LRC}, como descrito acima. A coluna Atributo usa: H (hexadecimal), N (numérico), A (alfabético), AN (alfanumérico), ANS (alfanumérico e caracteres especiais).

Y19 - Inicializar transação

Obrigatório para iniciar operações com cartão. O Host envia a chave RSA, o valor e os parâmetros de criptografia; o Pinpad retorna os dados do cartão (fluxo contactless).

Requisição Y19 (Host → Pinpad)

Campo	Tamanho	Atributo	Descrição
`RSA`	256–512	ANS	Chave pública RSA (módulo) usada para criptografar a Trilha 1. Veja Criptografia do Pinpad.
`EXP`	1–12	ANS	Expoente RSA.
`TEC`	3	N	Tempo limite entre comandos, em segundos (`000`–`999`).
`ET1`	1	N	Envia a Trilha 1 (banda). Sem uso: o valor é ignorado pelo Pinpad.
`PTC`	1	N	Solicita o tipo de conta (comum em cartões MAESTRO).
`PMK`	1	AN	Posição da chave mestra (`0`–`9` ou `N`). PMK do PIN = valor; PMK do PAN = valor + 1.
`WRK`	1–16	ANS	Chave de trabalho.
`ENC`	1	N	Criptografia DUKPT do PAN: `0` desativada, `1` ativada, `2` ativada usando o slot 3.
`IMP`	12	N	Valor da compra; os dois últimos dígitos são decimais.
`ICB`	12	N	Valor do cashback (`000000000000` se não usado); os dois últimos dígitos são decimais.
`TTY`	2	N	Tipo de transação. Veja Tabelas de Códigos.

Resposta Y19 (Pinpad → Host) — Contactless

Campo	Tamanho	Atributo	Descrição
`TJA`	1–19	N	Número do cartão (8 primeiros e 4 últimos dígitos; o restante mascarado com `*`). Vem da Trilha II.
`CSE`	3	N	Código de serviço (da Trilha II); enviado em texto claro.
`CBC`	3	N	Código do banco. Sem uso: sempre `000`.
`NYA`	1–26	ANS	Nome do portador do cartão para o comprovante (Trilha I ou TAG 5F20); preenchido à direita com espaços.
`REG`	6	N	Número do registro. Sem uso: `000041`.
`MDI`	1	A	Modo de entrada (`M`, `B`, `C`, `L`, `E`). Veja Tabelas de Códigos.
`VER`	1–15	ANS	Versão do software do Pinpad.
`FDV`	4	N	Data de validade (`YYMM`), da Trilha II.
`TC2`	256–512	ANS	Trilha II criptografada com a chave RSA do Y19. Vem da Trilha II ou da TAG 57.
`1NL`	1	N	Indicador de Trilha I não lida: `0` lida, `1` não lida.
`NSF`	1–12	N	Número de série físico do Pinpad.
`CPG`	1–300	ANS	Criptograma EMV (TLV). `N` se não se aplicar.
`CAU`	6	N	Código de autorização. Retornado como 6 espaços em branco.
`CRE`	2	N	Código de resposta do emissor (TAG 8A e resultado do SDK).
`NSP`	3	N	Número de sequência do PAN (TAG 5F34).
`APN`	0–32	ANS	Nome da aplicação EMV selecionada, em hexadecimal, para o comprovante (TAG 9F12 / TAG 50).
`AID`	0–16	ANS	Identificador da aplicação EMV selecionada (TAG 4F).
`KSN-PAN`	20	H	Key Serial Number do PAN criptografado com DUKPT.
`ENC-PAN`	1–256	ANS	Criptograma do PAN criptografado com DUKPT.
`TDC`	1	AN	Tipo de conta (MAESTRO). `N` para não imprimir.
`PIN`	16–32	ANS	PINBLOCK, se um PIN foi digitado; caso contrário, omitido.
`KSN`	20	N	Key Serial Number do PIN DUKPT; incrementa a cada operação EMV com PIN. Omitido se não houver PIN.

Y02 - Resposta de dados adicionais

Gerado pelo Pinpad após a leitura de um cartão. A requisição pode atualizar valores e solicitar dados de banda; a estrutura da resposta depende do modo de entrada (BANDA ou CHIP).

Requisição Y02 (Host → Pinpad)

Campo	Tamanho	Atributo	Descrição
`U4D`	1	N	Solicita os 4 últimos dígitos (somente banda).
`CDS`	1	N	Solicita o código de segurança (somente banda).
`ET1`	1	N	Envia a Trilha 1 (banda). Sem uso: o valor é ignorado.
`SPI`	1	N	Solicita o PIN (somente banda).
`PTC`	1	N	Solicita o tipo de conta (comum em MAESTRO).
`PMK`	1	AN	Posição da chave mestra (`0`–`9` ou `N`). PMK do PIN = valor; PMK do PAN = valor + 1.
`WRK`	1–16	ANS	Chave de trabalho (`N` se não estiver solicitando PIN nem criptografia de trilhas). Sem uso: o valor é ignorado.
`ENC`	1	N	Criptografia DUKPT do PAN: `0` desativada, `1` ativada, `2` ativada usando o slot 3.
`IMP`	12	N	Valor da compra; atualiza o valor de `Y19.IMP`.
`ICB`	12	N	Valor do cashback; atualiza o valor de `Y19.ICB`.

Resposta Y02 (Pinpad → Host) — Banda magnética (BANDA)

Campo	Tamanho	Atributo	Descrição
`TJA`	1–19	N	Número do cartão (8 primeiros e 4 últimos; o restante mascarado com `*`). Vem da Trilha II.
`FDV`	4	N	Data de validade (`YYMM`), da Trilha II.
`TC1`	256–512	ANS	Trilha I criptografada com a chave RSA do Y19 (banda).
`TC2`	256–512	ANS	Trilha II criptografada com a chave RSA do Y19 (banda).
`1NL`	1	N	Indicador de Trilha I não lida: `0` lida, `1` não lida.
`CDS`	1–4	N	Código de segurança criptografado com a chave RSA do Y19 (digitado pelo usuário).
`NSF`	1–12	N	Número de série físico do Pinpad.
`KSN-PAN`	20	H	Key Serial Number do PAN criptografado com DUKPT.
`ENC-PAN`	1–256	ANS	Criptograma do PAN criptografado com DUKPT.
`TDC`	1	AN	Tipo de conta (MAESTRO). `N` para não imprimir.
`PIN`	16–32	ANS	PINBLOCK, se um PIN foi digitado; caso contrário, omitido.
`KSN`	20	N	Key Serial Number do PIN DUKPT; incrementa a cada operação com PIN.

Resposta Y02 (Pinpad → Host) — Chip (CHIP)

Campo	Tamanho	Atributo	Descrição
`TJA`	1–19	N	Número do cartão (8 primeiros e 4 últimos; o restante mascarado com `*`). Vem da Trilha II.
`FDV`	4	N	Data de validade (`YYMM`), da Trilha II.
`TC2`	256–512	ANS	Trilha II criptografada com a chave RSA do Y19. Vem da TAG 57 (chip).
`1NL`	1	N	Indicador de Trilha I não lida: `0` lida, `1` não lida.
`NSF`	1–12	N	Número de série físico do Pinpad.
`CPG`	1–300	ANS	Criptograma EMV (formato TLV). `N` se nenhuma informação for enviada.
`CAU`	6	N	Código de autorização. Retornado como 6 espaços em branco.
`CRE`	2	N	Código de resposta do emissor.
`NSP`	3	N	Número de sequência do PAN (TAG 5F34).
`APN`	0–32	ANS	Nome da aplicação EMV selecionada, em hexadecimal, para o comprovante (TAG 9F12 / TAG 50).
`AID`	0–16	ANS	Identificador da aplicação EMV selecionada (TAG 4F).
`KSN-PAN`	20	H	Key Serial Number do PAN criptografado com DUKPT.
`ENC-PAN`	1–256	ANS	Criptograma do PAN criptografado com DUKPT.
`TDC`	1	AN	Tipo de conta (MAESTRO). `N` para não imprimir.
`PVF`	1	N	Indicador de PIN offline verificado pelo cartão. Deve ser `0` para PIN online.
`PIN`	16–32	ANS	PINBLOCK, se um PIN foi digitado; caso contrário, omitido.
`KSN`	20	N	Key Serial Number do PIN DUKPT; incrementa a cada operação EMV com PIN.

Y03 - Autorização do Host

A instrução final enviada pelo Host para concluir o fluxo.

Campos principais [Host]:

[CAU]: Código de autorização do emissor.
[CRE]: Código de resposta (por exemplo, “00” para sucesso).

Tratamento de erros (Y0E)

Se uma operação falhar, o terminal retorna um relatório Y0E em vez da resposta esperada da sequência.

Código	Mensagem	Descrição
01	CANCELADO	Cancelamento iniciado pelo usuário ou pelo Host.
04	ERROR EMV	Falha na leitura do chip ou de protocolo.
08	SIN LLAVES	Chaves DUKPT ausentes no Slot 3.