> For the complete documentation index, see [llms.txt](https://ftcoders.first-tech.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ftcoders.first-tech.com/landing-page/modulo-cvv/erros-troubleshooting-e-apendices.md).

# 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 :

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

### 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 :

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

### 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):

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Posição</th><th>Significado</th><th>Exemplos de Valor</th></tr></thead><tbody><tr><td>1º dígito</td><td>Tecnologia e uso internacional</td><td><code>1</code> = internacional, <code>2</code> = internacional (chip obrigatório), <code>5</code> = nacional, <code>6</code> = nacional (chip), <code>9</code> = teste.</td></tr><tr><td>2º dígito</td><td>Verificação de autorização</td><td><code>0</code> = normal, <code>2</code> = online via emissor, <code>4</code> = verificação obrigatória pelo emissor.</td></tr><tr><td>3º dígito</td><td>Serviços permitidos / PIN</td><td><code>0</code> = sem restrição (PIN obrigatório), <code>1</code> = sem restrição, <code>5</code> = bens e serviços (PIN obrigatório), <code>7</code> = apenas <em>cash</em>.</td></tr></tbody></table>

{% hint style="info" %}

#### 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.
{% endhint %}

#### Apêndice B. Glossário

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ftcoders.first-tech.com/landing-page/modulo-cvv/erros-troubleshooting-e-apendices.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.