> 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-emv/codigos-de-erro-e-troubleshooting.md).

# Códigos de Erro e Troubleshooting

Esta secção unifica o catálogo completo de erros da API e o guia de resolução rápida para os problemas mais comuns encontrados durante a integração.

### Taxonomia Completa de Códigos de Erro (`retCode`)

Nas respostas de erro (HTTP `400`, `404`, `500`), o campo `retCode` carrega um código específico que identifica a categoria exata da falha.

A tabela abaixo consolida todos os códigos documentados, com a respetiva orientação de diagnóstico e ação sugerida:

<table data-header-hidden="false" data-header-sticky><thead><tr><th>retCode</th><th>Significado</th><th>Ação Sugerida</th></tr></thead><tbody><tr><td><code>01</code></td><td>Falha na verificação do ARQC/TC/AAC/MPVV</td><td>O ARQC recebido não é válido para o cartão/chave informados. Verificar PAN, PSN, <code>mkacKeyId</code> e o conteúdo do campo 55.</td></tr><tr><td><code>03</code></td><td>Padding Flag inválido</td><td>Configuração de <em>padding</em> do criptograma está incompatível com o esquema selecionado. Revisar <code>schemeId</code>.</td></tr><tr><td><code>04</code></td><td>Mode Flag não reconhecido</td><td>Valor de <code>mode</code> fora da faixa suportada. Ver secção de modos de operação.</td></tr><tr><td><code>05</code></td><td>Scheme ID não reconhecido</td><td>Valor de <code>schemeId</code> fora da faixa suportada. Ver secção de bandeiras suportadas.</td></tr><tr><td><code>06</code></td><td>Valor YHHHHCC inválido</td><td>Parâmetro interno de derivação inválido. Validar combinação <code>schemeId</code> x <code>brand</code> e reportar ao suporte se persistir.</td></tr><tr><td><code>10</code></td><td>Erro de paridade na chave MK</td><td>Problema na chave MK-AC armazenada. Não é um erro de payload. Abrir chamado com o suporte técnico da First Tech.</td></tr><tr><td><code>52</code></td><td>Branch/Height inválido</td><td>Parâmetro <code>branch_height_params</code> incompatível com o esquema. Confirmar se o esquema requer esse parâmetro.</td></tr><tr><td><code>68</code></td><td>Comando desabilitado</td><td>O comando EMV está desabilitado para o <code>client_id</code>/contrato. Contatar o suporte First Tech para validar a habilitação.</td></tr><tr><td><code>F1</code></td><td>Método de derivação de chave inválido</td><td>O método de derivação inferido a partir do <code>schemeId</code> está incompatível com a MK-AC. Revisar perfil do cartão.</td></tr><tr><td><code>F2</code></td><td>Método de validação ARQC inválido</td><td>Método de validação inconsistente com o esquema. Revisar <code>schemeId</code> e <code>mode</code>.</td></tr><tr><td><code>F3</code></td><td>Algoritmo da chave MK-AC não é AES</td><td>O esquema selecionado exige MK-AC AES, mas a chave provisionada usa outro algoritmo. Verificar onboarding da chave.</td></tr><tr><td><code>F5</code></td><td>Método de chave de sessão inválido</td><td>Incompatibilidade entre o método de <em>session key</em> do esquema e a configuração do HSM.</td></tr><tr><td><code>F8</code></td><td>Método de geração de chave OTPK inválido</td><td>Método OTPK incompatível com o esquema. Revisar <code>schemeId</code>.</td></tr></tbody></table>

### Interpretação Rápida dos Códigos

* **Problemas na Aplicação (Cliente):** A maioria dos códigos (`01`, `03-06`, `52`, `F1-F8`) indica problema no payload enviado ou na configuração do cartão/esquema. A correção deve ser feita no seu código.
* **Problemas de Infraestrutura (First Tech):** Os códigos `10` (paridade da chave MK) e `68` (comando desabilitado) indicam falha no provisionamento do lado da First Tech. A correção depende da abertura de chamado técnico.

### Guia de Troubleshooting

A tabela abaixo organiza os sintomas mais frequentes relatados nas integrações, as suas causas prováveis e as ações sugeridas. Para casos não cobertos, abra um chamado em `api.hop@first-tech.com`

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Sintoma Observado</th><th>Causa Provável</th><th>Ação Sugerida</th></tr></thead><tbody><tr><td>HTTP 401 intermitente</td><td>Token JWT a expirar entre chamadas.</td><td>Implementar renovação proativa do token e <em>fallback</em> reativo em caso de 401.</td></tr><tr><td>HTTP 401 consistente</td><td>Credenciais OAuth2 inválidas ou <em>audience</em> errada.</td><td>Validar <code>client_id</code>/<code>client_secret</code> e se a <em>audience</em> é a correta (<code>https://auth-jwt-authorize-prd-first-tech</code>).</td></tr><tr><td>HTTP 404 ("chave não encontrada")</td><td><code>mkacKeyId</code> inexistente para o <code>client_id</code> atual ou ambiente trocado (PRD vs HML).</td><td>Confirmar o <code>mkacKeyId</code> com a equipa da First Tech e validar o ambiente.</td></tr><tr><td>HTTP 400 (retCode = 01)</td><td>ARQC não confere com a chave/cartão.</td><td>Revisar PAN, PSN, <code>field55EmvTags</code> e <code>schemeId</code>. Se tudo estiver correto, o cartão foi adulterado ou sofreu colisão; recusar transação.</td></tr><tr><td>HTTP 400 (retCode = 04)</td><td><code>mode</code> fora da faixa suportada.</td><td>Revisar os valores permitidos: 0, 1, 2, 3, 4, 5, 6, 8, 9.</td></tr><tr><td>HTTP 400 (retCode = 05)</td><td><code>schemeId</code> fora da faixa suportada.</td><td>Confirmar o perfil criptográfico do cartão com o emissor/bandeira.</td></tr><tr><td>retCode = F1 / F2 / F5 / F8</td><td>O <code>schemeId</code> selecionado não é compatível com o método de derivação da chave MK-AC provisionada.</td><td>Revisar combinação <code>schemeId</code> x <code>brand</code> e verificar se a chave referenciada em <code>mkacKeyId</code> é a correta.</td></tr><tr><td>HTTP 500 ocasional</td><td>Falha transitória do serviço.</td><td><p>Aplicar <em>retry</em> com <em>backoff</em> (ex.: 3 tentativas com 100ms, 400ms, 1s). Se persistir, abrir chamado.</p><p><a class="button secondary"></a></p></td></tr><tr><td>Latência acima do esperado</td><td><em>Round-trip</em> adicional por uso de <code>mode=0</code> seguido de <code>mode=2</code> ou <code>4</code>.</td><td><p>Migrar para um modo combinado (<code>1</code>, <code>3</code> ou <code>5</code>) quando a lógica do emissor permitir.</p><p><a class="button secondary"></a></p></td></tr></tbody></table>

## Integração Prática: Fluxos e Exemplos

Esta secção reúne o roteiro prático para colocar o módulo EMV em produção, incluindo boas práticas, armadilhas comuns e exemplos reais de JSON para os cenários mais frequentes .

### Fluxo Recomendado de Integração

A integração típica segue cinco etapas lógicas que aceleram o tempo até a primeira transação validada :

* **Onboarding de Credenciais:** Obtenha o `client_id`, `client_secret` e o identificador da chave (`mkacKeyId`). Valide o fluxo OAuth2 e teste uma chamada trivial em homologação para confirmar o token .
* **Mapeamento dos Dados EMV:** Identifique onde os dados EMV chegam (geralmente via campo 55 da ISO 8583). Mapeie o PAN, PSN e garanta que o formato TLV hexadecimal é preservado no `field55EmvTags` .
* **Decisão do Modo de Operação:** Para autorizações online, selecione `mode=1` (ARC) ou `mode=3` (CSU). Dê preferência a modos combinados para poupar *round-trips* ao HSM .
* **Testes em Homologação:** Execute os seguintes cenários de teste obrigatórios:
  * ARQC válido + aprovação (`arc=00`)
  * ARQC válido + negação (`arc=05`)
  * ARQC inválido (cartão adulterado)
  * Chave inexistente / Modo inválido.
* **Go-Live e Monitorização:** Na janela de corte produtivo, monitorize nas primeiras 24-72h a latência, a taxa de sucesso e possíveis erros 401 (problemas de token) . Configure alertas críticos para `retCode` 10 e 68.

### Boas Práticas e Armadilhas Comuns

Antes de analisar os payloads, valide se a sua implementação cumpre estes requisitos vitais:

**Boas Práticas:**

* **Preservar o formato TLV do campo 55:** O valor de `field55EmvTags` deve ser passado exatamente como recebido, em hexadecimal. Evite manipulações de *string* (remoção de espaços, conversão de *case*), pois isso corrompe o formato. A extração da tag `9F26` é feita internamente pelo serviço.
* **Pin de `schemeId` por BIN:** Mantenha uma tabela interna no emissor que mapeia `BIN` ➔ `brand` ➔ `schemeId`. É a forma mais segura de selecionar os parâmetros corretos por cartão.
* **Idempotência no Cliente:** A API não oferece idempotência nativa. Implemente-a localmente com um *cache* de respostas por alguns segundos para contornar *timeouts* ou *retries* de rede.

{% hint style="warning" %}

#### As 5 Armadilhas mais comuns na integração:

1\. `mkacKeyId` com `client_id` errado (Gera HTTP 404) .

2\. `schemeId` incompatível com o cartão (Gera retCode F1, F2 ou F5) .

3\. Enviar `mode` que obriga `arc` ou `csu`, mas esquecer de preencher o campo (Gera HTTP 400 com retCode 04).

4\. Alterar qualquer byte no `field55EmvTags`, corrompendo o TLV.

5\. Reutilizar token JWT já expirado, travando o lote de transações.
{% endhint %}

### Exemplos Práticos por Cenário

Os exemplos abaixo ilustram os usos mais frequentes. *Nota: Os payloads estão simplificados para foco didático e os valores reais dependerão do cartão e do ambiente* .

#### Cenário 1: Autorização online com ARPC método 1 (ARC)

Fluxo mais comum em emissores tradicionais. Em uma única chamada, o ARQC é validado e o ARPC é gerado com base no código de resposta (`arc=00`) .

**Request** (`POST /ValidateARQC4x`):

```json
JSON
{
  "client_id": 8,
  "brand": "VISA",
  "mode": "1",
  "schemeId": "0",
  "iv_ac": null,
  "branch_height_params": null,
  "mkacKeyId": "client-8-mk-ac-visa",
  "pan": "4111111111111111",
  "panSeqNr": "00",
  "field55EmvTags": "9F2608...9F3602003F...",
  "arc": "00"
}
```

**Response** (Aprovação):

```json
JSON
{
  "retCode": 0,
  "retValue": "70EFBFBDD89DEFBF",
  "retValid": true,
  "retDescription": "OK"
}
```

#### Cenário 2: Autorização online com ARPC método 2 (CSU)

Fluxo para esquemas modernos (Visa qVSDC, Mastercard M/Chip Advance). O `csu` de 4 bytes substitui o `arc` e o `mode` é alterado para `3` .

**Request** (`POST /ValidateARQC4x`):

```json
JSON
{
  "client_id": 8,
  "brand": "VISA",
  "mode": "3",
  "schemeId": "9",
  "iv_ac": null,
  "branch_height_params": null,
  "mkacKeyId": "client-8-mk-ac-visa-qvsdc",
  "pan": "4111111111111111",
  "panSeqNr": "00",
  "field55EmvTags": "9F2608...",
  "csu": "03820000"
}
```

#### Cenário 3: Apenas validar ARQC (Sem gerar ARPC)

Útil quando a geração do ARPC acontece numa etapa posterior. O `retValue` ficará vazio .

```json
JSON
{
  "client_id": 8,
  "brand": "MASTERCARD",
  "mode": "0",
  "schemeId": "1",
  "mkacKeyId": "client-8-mk-ac-mc",
  "pan": "5555555555554444",
  "panSeqNr": "00",
  "field55EmvTags": "9F2608..."
}
```

#### Cenário 4: Gerar ARPC sem revalidar ARQC

Evita uma segunda verificação criptográfica, reduzindo latência, útil quando a validação já foi feita antes. Obriga informar o `arc` (ou `csu`) .

```json
JSON
{
  "client_id": 8,
  "brand": "MASTERCARD",
  "mode": "2",
  "schemeId": "1",
  "mkacKeyId": "client-8-mk-ac-mc",
  "pan": "5555555555554444",
  "panSeqNr": "00",
  "field55EmvTags": "9F2608...",
  "arc": "00"
}
```

#### Cenário 5: ARQC Inválido (Cartão Recusado)

Quando o ARQC recebido não corresponde à chave do emissor, a API retorna erro com `retCode = 1`. A aplicação deve tratar este caso imediatamente como transação recusada .

**Response de Erro:**

```json
JSON
{
  "retCode": 1,
  "retValue": "",
  "retMultiValue": null,
  "retValid": false,
  "retDesc": "Warning: ARQC/TC/AAC/MPVV verification failure"
}
```


---

# 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-emv/codigos-de-erro-e-troubleshooting.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.