Erros, Troubleshooting e Apêndices

Esta página consolida o material de suporte para diagnóstico rápido e consulta de referências normativas do ecossistema de pagamentos aplicadas ao módulo CVV.

Catálogo de Códigos de Erro (retCode)

O campo retCode segue a convenção de que 0 representa sucesso. Qualquer outro valor indica uma falha criptográfica ou inconsistência de dados rejeitada diretamente pelo HSM.

A tabela abaixo lista os códigos de erro oficiais e a ação corretiva recomendada :

Código	Significado	Origem	Ação Recomendada
01	Falha na verificação do CVV / criptograma.	HSM	CVV inválido — recusar a transação ou solicitar nova entrada do CVV ao utilizador.
05	Scheme, Version ID ou Key Derivation Method não reconhecido.	HSM	Verificar os valores enviados nos campos brand, dynCvVers e kdm no VerifyDynCV.
06	Valor YHHHHCC inválido.	HSM	Erro interno de derivação criptográfica. Abrir chamado com o suporte técnico.
10	Erro de paridade na chave CVK ou MKAC.	HSM	A chave referenciada pelo keyId está corrompida. Recadastrar a chave via módulo Key Manager.
27	CVK não é double length.	HSM	A chave CVK tem de ter o comprimento correto (DES double-length). Recadastrar a chave.
52	CVS inválido.	HSM	Verificar os campos discretionary em transações específicas.
68	Comando desabilitado.	HSM	A operação solicitada está desabilitada na configuração do HSM. Contatar o suporte da First Tech.
E9	Valor de máscara CVC3 inválido.	HSM	Específico do MasterCard CVC3. Verificar a configuração de bandeira enviada.
EA	Modified PSN Flag inválido.	HSM	Específico do MasterCard. Verificar o valor fornecido no campo psn.

Guia de Troubleshooting

A tabela a seguir cruza os sintomas mais comuns observados nas integrações iniciais com as suas prováveis causas e formas de resolução :

Sintoma Observado	Causa Provável	Como Resolver
HTTP 401 em todas as chamadas	Token JWT expirado ou audience errado.	Renovar o token via Auth0; conferir se a audience configurada no OAuth é a correta para a API.
HTTP 404 (com retCode 0)	O keyId não está cadastrado para este client_id, ou há um erro de digitação no alias.	Listar as chaves no módulo Key Manager e conferir o nome exato.
HTTP 400 (com retCode 10)	Erro de paridade na chave CVK (a chave foi importada incorretamente ou está corrompida).	Recadastrar a chave no Key Manager utilizando o KCV (Key Check Value) correto.
HTTP 400 (com retCode 27)	A CVK foi cadastrada como single-length, mas as operações de CVV exigem double-length.	Recadastrar a chave com o comprimento adequado.
HTTP 400 (com retCode 05 no VerifyDynCV)	Combinação inválida entre brand, dynCvVers e kdm.	Tipicamente causado por enviar um dynCvVers (versão) fora dos valores aceitáveis pela bandeira.
O CVV gerado não bate com o impresso no plástico	O formato do expDate diverge entre o que foi enviado (ex: YYMM vs MMYY).	Validar a configuração do HSM para o seu tenant e padronizar o formato em todas as chamadas.
SuperGenerateCV retorna um array com tamanho inesperado	Há service codes duplicados no array de entrada.	Garantir que o array enviado corresponde de forma 1:1 ao retorno; se precisar de duplicatas, faça chamadas isoladas.
Latência alta intermitente	Reuso excessivo de uma única conexão HTTP ou ausência de keep-alive.	Habilitar keep-alive no seu cliente HTTP. A API mantém um pool otimizado com o HSM, mas a conexão entre si e a API REST depende do seu código cliente.

Apêndice A. Service Codes (ISO 7813)

O service code é um campo de três dígitos presente na tarja magnética e no chip, responsável por definir a tecnologia, restrições geográficas e serviços do cartão. O módulo utiliza-o como insumo criptográfico para o cálculo do CVV1 .

Estrutura Padrão (ISO/IEC 7813):

Posição	Significado	Exemplos de Valor
1º dígito	Tecnologia e uso internacional	1 = internacional, 2 = internacional (chip obrigatório), 5 = nacional, 6 = nacional (chip), 9 = teste.
2º dígito	Verificação de autorização	0 = normal, 2 = online via emissor, 4 = verificação obrigatória pelo emissor.
3º dígito	Serviços permitidos / PIN	0 = sem restrição (PIN obrigatório), 1 = sem restrição, 5 = bens e serviços (PIN obrigatório), 7 = apenas cash.

Comportamento Especial na Hop V4

Independentemente da norma ISO 7813, a plataforma Hop trata os valores "000" e "999" como sinalizadores semânticos na requisição: * "000": Indica que o CVV a ser gerado/validado é o CVV2 (impresso no plástico) . * "999": Indica tratar-se de um dCVV/CVC3 dinâmico. * Para o CVV1, deve submeter o valor real do service code do cartão.

Apêndice B. Glossário

Sigla	Significado	Contexto de Uso
ATC	Application Transaction Counter	Contador interno do cartão chip que incrementa a cada transação. Insumo vital para o cálculo do dCVV/CVC3.
CVK	Card Verification Key	Chave criptográfica simétrica (geralmente DES double-length) usada para gerar e validar CVVs estáticos (CVV1, CVV2).
CVV / CVC	Card Verification Value / Code	Código curto que verifica a posse do cartão. CVV é o termo da Visa; CVC é o termo da MasterCard.
CVV1 / CVC1	CVV gravado na tarja ou chip	Estático. Utiliza o service code real do cartão como insumo.
CVV2 / CVC2	CVV impresso no verso do cartão	Estático. Referenciado pelo service code "000" na Hop V4.
CVC3 / dCVV	CVV dinâmico	Recalculado a cada transação (contactless/chip). Referenciado pelo service code "999".
HSM	Hardware Security Module	Dispositivo físico seguro que armazena as chaves criptográficas e executa as operações de cifragem sob proteção da LMK.
JWT	JSON Web Token	Padrão do token de autenticação emitido pelo Auth0 e utilizado no cabeçalho HTTP.
KCV	Key Check Value	Hash curto que comprova a integridade de uma chave após a sua importação para o HSM.
KDM	Key Derivation Method	Método utilizado pelo HSM para derivar a chave única da transação a partir da MKAC.
LMK	Local Master Key	Chave-mestra residente no HSM, responsável por proteger todas as outras chaves armazenadas na base de dados.
MKAC	Master Key for Application Cryptogram	Chave-mestra do emissor, usada para derivar as chaves de transação em operações de validação dinâmica (dCVV e EMV).
PAN	Primary Account Number	Número principal do cartão de pagamento (até 19 dígitos).
PSN	PAN Sequence Number	Número que diferencia múltiplos cartões associados ao mesmo PAN (ex.: titular e adicional).
UN	Unpredictable Number	Número pseudo-aleatório (nonce) gerado pelo terminal de pagamento para prevenir ataques de repetição (replay).