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)
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:
01
Falha na verificação do ARQC/TC/AAC/MPVV
O ARQC recebido não é válido para o cartão/chave informados. Verificar PAN, PSN, mkacKeyId e o conteúdo do campo 55.
03
Padding Flag inválido
Configuração de padding do criptograma está incompatível com o esquema selecionado. Revisar schemeId.
04
Mode Flag não reconhecido
Valor de mode fora da faixa suportada. Ver secção de modos de operação.
05
Scheme ID não reconhecido
Valor de schemeId fora da faixa suportada. Ver secção de bandeiras suportadas.
06
Valor YHHHHCC inválido
Parâmetro interno de derivação inválido. Validar combinação schemeId x brand e reportar ao suporte se persistir.
10
Erro de paridade na chave MK
Problema na chave MK-AC armazenada. Não é um erro de payload. Abrir chamado com o suporte técnico da First Tech.
52
Branch/Height inválido
Parâmetro branch_height_params incompatível com o esquema. Confirmar se o esquema requer esse parâmetro.
68
Comando desabilitado
O comando EMV está desabilitado para o client_id/contrato. Contatar o suporte First Tech para validar a habilitação.
F1
Método de derivação de chave inválido
O método de derivação inferido a partir do schemeId está incompatível com a MK-AC. Revisar perfil do cartão.
F2
Método de validação ARQC inválido
Método de validação inconsistente com o esquema. Revisar schemeId e mode.
F3
Algoritmo da chave MK-AC não é AES
O esquema selecionado exige MK-AC AES, mas a chave provisionada usa outro algoritmo. Verificar onboarding da chave.
F5
Método de chave de sessão inválido
Incompatibilidade entre o método de session key do esquema e a configuração do HSM.
F8
Método de geração de chave OTPK inválido
Método OTPK incompatível com o esquema. Revisar schemeId.
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) e68(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
HTTP 401 intermitente
Token JWT a expirar entre chamadas.
Implementar renovação proativa do token e fallback reativo em caso de 401.
HTTP 401 consistente
Credenciais OAuth2 inválidas ou audience errada.
Validar client_id/client_secret e se a audience é a correta (https://auth-jwt-authorize-prd-first-tech).
HTTP 404 ("chave não encontrada")
mkacKeyId inexistente para o client_id atual ou ambiente trocado (PRD vs HML).
Confirmar o mkacKeyId com a equipa da First Tech e validar o ambiente.
HTTP 400 (retCode = 01)
ARQC não confere com a chave/cartão.
Revisar PAN, PSN, field55EmvTags e schemeId. Se tudo estiver correto, o cartão foi adulterado ou sofreu colisão; recusar transação.
HTTP 400 (retCode = 04)
mode fora da faixa suportada.
Revisar os valores permitidos: 0, 1, 2, 3, 4, 5, 6, 8, 9.
HTTP 400 (retCode = 05)
schemeId fora da faixa suportada.
Confirmar o perfil criptográfico do cartão com o emissor/bandeira.
retCode = F1 / F2 / F5 / F8
O schemeId selecionado não é compatível com o método de derivação da chave MK-AC provisionada.
Revisar combinação schemeId x brand e verificar se a chave referenciada em mkacKeyId é a correta.
HTTP 500 ocasional
Falha transitória do serviço.
Aplicar retry com backoff (ex.: 3 tentativas com 100ms, 400ms, 1s). Se persistir, abrir chamado.
Latência acima do esperado
Round-trip adicional por uso de mode=0 seguido de mode=2 ou 4.
Migrar para um modo combinado (1, 3 ou 5) quando a lógica do emissor permitir.
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_secrete 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) oumode=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
retCode10 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
field55EmvTagsdeve 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 tag9F26é feita internamente pelo serviço.Pin de
schemeIdpor BIN: Mantenha uma tabela interna no emissor que mapeiaBIN➔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.
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.
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):
Response (Aprovação):
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):
Cenário 3: Apenas validar ARQC (Sem gerar ARPC)
Útil quando a geração do ARPC acontece numa etapa posterior. O retValue ficará vazio .
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) .
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:
Last updated