# Developer Platform
Welcome to your team’s developer platform
First Code
Guias, referências e manuais para integração de segurança criptográfica e ecossistemas de pagamento.
### Construa o futuro dos pagamentos.
Explore a documentação oficial da First Tech. Descubra como os nossos produtos funcionam, entenda os fluxos de integração e acesse as referências técnicas para escalar a sua operação financeira com segurança e agilidade.
### Explore os Nossos Produtos
Cover image
Hop API
Criptografia e segurança de ponta a ponta abstraída em APIs REST. Ideal para emissores e processadoras que precisam de gerir PIN, EMV, CVV e chaves criptográficas sem gerir hardware.
A solução SoftPOS que transforma dispositivos Android em terminais de pagamento. Aceda aos guias de experiência do utilizador (UX) e às documentações do SDK para captura segura de dados.
Infraestrutura criptográfica em nuvem (Cloud HSM) orientada a ambientes críticos de produção. Os manuais operacionais detalham a arquitetura de alta disponibilidade, resiliência e escalabilidade para operações de geração de chaves, criptografia de dados, assinatura digital e validação de transações.
### Conceitos e Fluxos de Integração
Entenda o funcionamento da plataforma antes de iniciar a implementação técnica.
* 🏢 Arquitetura e Ambientes Aprenda como separamos Homologação (Staging) e Produção, e quais as topologias de rede recomendadas para a sua integração.
* 🛡️ Conformidade e Segurança (PCI) Veja como as nossas soluções garantem a conformidade do seu negócio com as normas rigorosas PCI-PIN, PCI-DSS e PCI-HSM.
* 🔑 Autenticação de Sistemas Compreenda os fluxos de permissão, gestão de utilizadores e a autenticação segura baseada em tokens (OAuth2/JWT).
### Referência Técnica e Ferramentas
Acelere o desenvolvimento com as nossas ferramentas prontas a usar.
Recurso
Descrição
API References
Contratos Swagger interativos. Valide schemas de request/response e teste requisições diretamente no navegador.
SDKs (Bibliotecas)
Guias detalhados de implementação, chamadas de métodos e arquitetura do SDK Android para o TTP.
Catálogo Global de Erros
Resolução de problemas (Troubleshooting), tradução de códigos de falha do HSM, erros de paridade e recusas operacionais.
Release Notes
Acompanhe o ciclo de vida das plataformas, depreciação de endpoints e changelogs técnicos.
# 👋 Bem-vindo - HoP API v4
Esta página contém a introdução para a documentação HoP API da First Tech
O HoP, a plataforma de HSM-as-a-Service da First Tech para o mercado de pagamentos, foi atualizado para a versão 4.0.
O Hop V4 é a nova geração de uma plataforma que já atende algumas das principais fintechs e processadoras do Brasil. Reescrevemos a arquitetura para resolver dores reais que clientes da v3 reportaram nos últimos anos e aproveitamos para embarcar tecnologias novas, como a **cripto-agilidade**, que garante que sua operação não fique refém de um único padrão.
### Público Alvo deste Documento
Este documento é destinado a:
* **Cliente novo do Hop V4**: você está conhecendo a plataforma agora e quer entender o que ela faz, como contratar e como começar a integrar.
* **Cliente em migração da V3**: você já é cliente Hop e precisa migrar do ambiente V3 (que será descontinuado em 31 de maio de 2026) para o V4.
### Pule direto para...
Se você só tem 5 minutos, pule direto para a seção que interessa:
Visão de Produto
O que é o Hop V4
V3 → V4
O que muda na migração
Documentação
Mapa da Documentação
FAQ
Sobre o Hop V4
Suporte e Contatos
Fale conosco
### Visão do Produto
O Hop é a plataforma de criptografia como serviço da First Tech para o mundo dos pagamentos. Através de uma API REST simples e segura, o cliente consome todas as operações criptográficas que tradicionalmente exigiriam um HSM (Hardware Security Module) dedicado, com geração e gestão de chaves, validação e tradução de PIN, geração de CVV dinâmico, validação EMV, operações RSA e criptografia de dados, sem precisar comprar, operar ou manter hardware próprio.
#### O que o Hop V4 entrega
O HoP API é uma plataforma de operações criptográficas de pagamento entregues via API REST. Autenticação OAuth2/JWT, chamadas padrão HTTPS, documentação completa em formato OpenAPI e cobertura ampla de cenários de pagamento (cartão de crédito, débito, PIN, EMV, pagamentos por aproximação e cartões virtuais).
• Principais Módulos
* **PayShield Key Manager**: Geração e importação de chaves de trabalho (ZMK, ZPK, CVK, DEK, ZEK, BDK, ZAK, KERG). Gestão centralizada do ciclo de vida de chaves criptográficas.
* **PayShield Crypto**: Criptografia e descriptografia de dados sensíveis (ECB, CBC, CFB8, CFB64) e geração/validação de MAC.
* **PayShield PIN**: Validação e tradução de PIN Blocks em todos os formatos ISO e proprietários de mercado (0, 1, 2, 3, 4 e variantes Visa, Amex, Mastercard).
* **PayShield CVV**: Geração e validação de CVV/CVC estáticos e dinâmicos, com suporte a múltiplos códigos de serviço por requisição.
* **PayShield EMV**: Validação de ARPC 4.x para transações EMV, com suporte completo às principais bandeiras (Visa, Mastercard, Elo, JCB, Hipercard, American Express, Discover, UnionPay).
* **PayShield PAN**: Operações sobre o PAN (geração de PIN, translate de PAN, internalization, embossing, tradução entre LMK e ZPK em 3DES e AES).
* **PayShield RSA**: Importação e exportação de chaves criptográficas sob chave pública RSA, com suporte a PKCS#1 v1.5 e OAEP (SHA-1 até SHA-512).
#### Os planos comerciais
O Hop V4 é oferecido em três planos, escolhidos a partir do volume e da maturidade da operação:
Plano
Para quem
Faixa
Start
Times técnicos avaliando a plataforma; fintechs em estágio inicial.
Ambientes de desenvolvimento, POCs e operações de baixo volume.
Fintech
Fintechs em produção, sub-adquirentes e processadoras em crescimento.
Volume médio, exigências de SLA produtivo.
Enterprise
Adquirentes, bandeiras e operações com necessidades específicas de SLA, customização e integração dedicada.
### Mudanças - V3 → V4
A versão V4 representa a nova geração da plataforma, com arquitetura reescrita para entregar mais performance, mais capacidade, mais resiliência e — pela primeira vez no mercado brasileiro de pagamentos — chaves geradas a partir de entropia de origem quântica certificada.
HSM na nuvem. Chaves de origem quântica. Cripto-agilidade de verdade.
Cripto-agilidade
Mais Performance
Mais Segurança
Garantia que sua operação não fique refém de um único padrão, permitindo a troca rápida e transparente de componentes criptográficos críticos
10 vezes mais Rápidos.
A nova versão mantém o mesmo consumo de recursos entregando 10 vezes mais performance paralela. Isso é mais robustez para você.
Entropia quântica
Chaves geradas a partir de aleatoriedade de origem quântica certificada, eliminando a previsibilidade de PRNGs tradicionais.
Para mais detalhes da migração verificar Manifesto\_Migracao\_Hop\_V4
### Documentação
#### Materiais de apoio
Para entender o produto, suporte com a migração de versão, release notes:
Documento
O que é
Quando ler
Para quem
Autenticação (OAuth2)
Guia detalhado do fluxo OAuth2 do HoP V4: Obtenção de token, escopos, refresh, expiração e tratamento de credenciais. Incluí exemplos de requisição
Antes da primeira chamada à API. Releitura ao implementar rotação de credenciais ou ao intefgrar novo ambiente.
Time técnico, desenvolvedores responsáveis pela integração
Tratamento de Erros
Catálogo de códigos de rro do HoP V4, com significado, causa provável, ação recomendada e severidade. Cobre erros HTTP. erros de negócio e erros criptográficos
Durante o desenvolvimento, ao implementar lógica de retry/fallback e em troubleshooting de produção.
Desenvolvedores, time de operações/SRE e suporte técnico.
Release Notes HoP API V4
Histórico cronológico de versões do HoP V4: Novas funcionalidades, correções, breaking changes e depreciações por versão.
Ao subir de versão, antes de planejar atualização de integração e períodicamente para acompanhar a evolução do produto.
Time técnico, arquitetos, time de produtos.
Manifesto de Migração V3 → V4
Documento detalhado com as 5 etapas da migração, prazos, responsáveis e checklists.
No kickoff da migração e durante toda a execução.
Cliente migrando da V3, time técnico do cliente, Onboarding.
#### Documentação Técnica — Módulos Criptográficos
Sete documentos técnicos completos, um por módulo. Cada documento traz: visão conceitual do módulo, referência completa de endpoints (estilo Swagger, com requests e responses), exemplos práticos e casos de uso reais.
Módulo
Endpoints principais
Status
Key Manager
Geração e importação de chaves (ZMK, ZPK, CVK, DEK, ZEK, BDK, ZAK, KERG).
{% hint style="info" %}
💡 DICA - Como escolher por onde começar
Se sua integração envolve PIN ou autorização de pagamento, comece por PIN. Se envolve emissão de cartão, comece por CVV e Key Manager. Se envolve transações EMV, abra PIN, EMV e Key Manager juntos. Em caso de dúvida, fale com o time técnico.
{% endhint %}
# Autenticação (OAuth2)
### Visão Geral
A segurança é a base do **HoP API v4**. Como lidamos com operações criptográficas e dados sensíveis, todas as requisições aos nossos serviços devem ser obrigatoriamente autenticadas.
Para facilitar sua integração e garantir o mais alto nível de segurança, utilizamos o padrão de mercado **OAuth2** (gerenciado via Auth0).
Nesta seção, você aprenderá como obter suas credenciais, gerar um token de acesso (`access_token`) e como enviá-lo corretamente no cabeçalho das suas requisições.
{% hint style="warning" %}
Atenção: Suas credenciais (`client_secret`) e seus tokens de acesso dão poder total sobre o seu ambiente criptográfico. Nunca exponha esses dados no front-end (navegadores ou aplicativos móveis) ou em repositórios públicos (como o GitHub).
{% endhint %}
***
### O Protocolo OAuth2 (M2M)
A HoP API v4 utiliza o padrão **OAuth2** através do fluxo de **Client Credentials** (Credenciais de Cliente).
Como a nossa infraestrutura foi desenhada para operações de backend (comunicação de servidor para servidor), este é o fluxo ideal para interações **Máquina-a-Máquina (M2M)**. Ele permite que a sua aplicação se autentique de forma autônoma e contínua, sem a necessidade de intervenção humana (como telas de login de usuários).
Essa abordagem garante o isolamento total da sua aplicação e a proteção dos dados durante operações criptográficas críticas, mantendo a sua integração em total conformidade com as normas de segurança do mercado.
### Obtenção de Credenciais (Webadmin)
Para se comunicar com a HoP API, sua aplicação precisará de duas chaves exclusivas: um **`Client_Id`** e um **`Client_Secret`**.
Por questões de segurança e controle de acesso, essas credenciais **não são geradas dinamicamente via API.**
{% hint style="warning" %}
**Pré-requisito Obrigatório:**\
Antes de prosseguir com qualquer teste ou integração, acesse a plataforma Webadmin (nosso portal de gestão de chaves) para provisionar e validar as suas credenciais. A geração do token de acesso não funcionará sem este passo.
{% endhint %}
### Endpoints de Autenticação (Auth0)
Para gerar o seu token de acesso, você fará uma requisição **`POST`** para o nosso servidor de autorização.
Lembre-se da regra de ouro: as credenciais geradas no **Webadmin de Sandbox** só funcionam na URL de Sandbox, e as credenciais do **Webadmin de Produção** só funcionam na URL de Produção.
Utilize o endpoint correspondente ao seu ambiente:
{% tabs %}
{% tab title="🧪 Ambiente de Testes (Sandbox)" %}
```http
https://auth-sandbox.first-tech.net/oauth/token
```
{% endtab %}
{% tab title="🚀 Ambiente de Produção" %}
```http
https://auth.first-tech.net/oauth/token
```
{% endtab %}
{% endtabs %}
### Parâmetros da Requisição (Payload)
A solicitação do token deve ser enviada via método **`POST`**. O corpo da requisição (body) deve conter os seguintes parâmetros no formato JSON:
`client_id` · *string* · **Obrigatório**
O identificador único da sua aplicação. Você deve obter este valor no painel do Webadmin.
`client_secret` · *string* · **Obrigatório**
A chave secreta da sua aplicação, também obtida no Webadmin. Nunca exponha este valor.
`audience` · *string* · **Obrigatório**
O identificador único do recurso (API) que você deseja acessar.
`grant_type` · *string* · **Obrigatório**
Define o fluxo de autenticação. Para interações máquina-a-máquina, deve ser estritamente
{% hint style="warning" %}
**Atenção ao campo** `audience`
O valor deste campo muda de acordo com o ambiente. Se você usar o `audience` de Sandbox apontando para a URL de Produção (ou vice-versa), o Auth0 emitirá um token inválido e suas chamadas ao HoP API serão rejeitadas. Confirme o valor correto no Webadmin.
{% endhint %}
### Exemplo de Requisição
Abaixo, apresentamos a estrutura da chamada. Lembre-se de configurar o cabeçalho `Content-Type` como `application/json` e substituir os valores de exemplo pelas suas credenciais reais obtidas no painel do Webadmin.
{% tabs %}
{% tab title="cURL" %}
```bash
curl --request POST \
--url https://auth.first-tech.net/oauth/token \
--header 'Content-Type: application/json' \
--data '{
"client_id": "SEU_CLIENT_ID_AQUI",
"client_secret": "SEU_CLIENT_SECRET_AQUI",
"audience": "https://api.first-tech.net/hop",
"grant_type": "client_credentials"
}'
```
{% endtab %}
{% tab title="HTTP (Raw)" %}
```http
POST /oauth/token HTTP/1.1
Host: auth.first-tech.net
Content-Type: application/json
{
"client_id": "SEU_CLIENT_ID_AQUI",
"client_secret": "SEU_CLIENT_SECRET_AQUI",
"audience": "https://api.first-tech.net/hop",
"grant_type": "client_credentials"
}
```
{% endtab %}
{% endtabs %}
### Resposta de Sucesso
Se as credenciais estiverem corretas, o servidor retornará um status **`200 OK`**. O corpo da resposta conterá o seu token de acesso (JWT) e o tempo de validade dele em segundos.
```json
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6...",
"token_type": "Bearer",
"expires_in": 86400
}
```
{% hint style="success" %}
**Melhor Prática: Faça cache do seu Token**
Para garantir altíssimo desempenho e evitar latência nas suas transações, **não gere um novo token a cada requisição.**
O valor retornado em `expires_in` (ex: 86400 segundos = 24 horas) indica quanto tempo essa chave é válida. A estratégia correta é salvar o `access_token` na memória da sua aplicação (cache) e reutilizá-lo em todas as chamadas ao HSM, solicitando um token novo apenas quando o atual estiver a poucos minutos de expirar. Isso também evita que você seja bloqueado por excesso de chamadas (*Rate Limiting*).
{% endhint %}
# Tratamento de Erros
Ao integrar com o HoP API, é importante entender que os erros podem ocorrer em duas camadas distintas: a camada de transporte (HTTP) e a camada de aplicação (HSM).
### Códigos de Status HTTP
A API utiliza os códigos de status padrão do protocolo HTTP para indicar o sucesso ou a falha básica de uma requisição. Falhas nesta camada geralmente indicam problemas de comunicação, formatação ou autenticação, antes mesmo da requisição chegar ao HSM.
`200` · ***Success***
A requisição foi recebida, compreendida e processada com sucesso.
{% hint style="info" %}
Nota: Um status **HTTP 200** não garante que a operação no HSM foi um sucesso, apenas que a comunicação ocorreu sem falhas. Sempre verifique o `retCode` no corpo da resposta.
{% endhint %}
`400` · ***Bad Request***
A requisição está malformada, faltando parâmetros obrigatórios ou com sintaxe JSON inválida.
`401` · ***Unauthorized***
O seu `access_token` é inválido, expirou ou não foi enviado no cabeçalho `Authorization`.
`402` · ***Over Quota***
A cota do seu plano para este endpoint foi excedida.
`404` · ***Not Found***
O endpoint ou recurso solicitado não existe. Verifique a URL da requisição.
`422` · ***Validation Error***
A requisição está bem formatada, mas contém erros de validação semântica (ex: um `keyName` que não existe).
`429` · ***Too Many Requests***
Você atingiu o limite de requisições por segundo (Rate Limit). Aguarde alguns instantes antes de tentar novamente.
`50X` · ***Internal Server Error***
Ocorreu um erro interno nos servidores do HoP API. Caso o erro persista, entre em contato com o suporte.
### Códigos de Resposta do HSM (retCode)
Mesmo que a sua requisição retorne um HTTP `200 Success`, a operação criptográfica dentro do HSM pode falhar (por exemplo, se você tentar validar um PIN incorreto ou usar uma chave incompatível).
O resultado real da operação do HSM sempre estará no campo `retCode` do corpo da resposta (JSON). Abaixo está a lista de códigos padrão e seus significados:
#### ✅ Sucesso
`00` · ***No error***
A operação criptográfica foi executada com sucesso absoluto. Não há erros.
***
#### 🔑 Erros de Validação e Chaves (01 a 29)
`01` · ***Verification failure or warning of imported key parity error***
Falha na verificação de criptogramas (ex: MAC ou Assinatura incorreta) ou aviso de que a chave importada possui erro de paridade.
`02` · ***Key inappropriate length for algorithm***
O tamanho da chave fornecida não é adequado para o algoritmo criptográfico solicitado (ex: tentar usar uma chave DES simples em uma operação TDES).
`04` · ***Invalid key type code***
O código do tipo de chave (`keyType` / `keyName`) enviado é inválido ou não é suportado por este endpoint.
`05` · ***Invalid key length flag***
A flag que define o tamanho da chave (Key Scheme, como U, T, X) é inválida.
`10` · ***Source key parity error***
Erro de paridade detectado na chave de origem (Source Key). A chave pode estar corrompida.
`11` · ***Destination key parity error or key all zeros***
Erro de paridade na chave de destino, ou a chave fornecida é composta apenas por zeros (chave nula).
`12` **· *****Contents of user storage not available. Reset, power-down or overwrite***
O conteúdo do armazenamento seguro não está disponível no momento.
`13` · ***Invalid LMK Identifier***
O identificador da Local Master Key (LMK) enviado ou configurado é inválido.
`14` · ***PIN encrypted under LMK pair 02-03 is invalid***
O bloco de PIN fornecido é inválido. Este é o erro mais comum quando um usuário digita a senha incorreta ou quando o PIN Block foi malformado na origem.
`15` · ***Invalid input data (invalid format, invalid characters, or not enough data provided)***
Os dados de entrada enviados na requisição são inválidos. Pode ser um formato incorreto, caracteres não permitidos ou falta de dados obrigatórios.
`16` · ***Console or printer not ready or not connected***
O HSM não consegue se comunicar com o console ou impressora interna (erro de infraestrutura).
`17` · ***Unrecognized message header***
O cabeçalho da mensagem enviada ao HSM não foi reconhecido.
`20` · ***PIN block does not contain valid values***
O formato do PIN Block fornecido contém valores que não respeitam o padrão matemático exigido (ex: ISO 0, ISO 1).
`21` · ***Invalid index value***
O valor de índice (Index Value) fornecido para derivação de chaves é inválido.
`22` · ***Invalid account number***
O Número da Conta (PAN / Número do Cartão) fornecido é inválido ou não condiz com o bloco de PIN.
`23` · ***Invalid PIN block format code***
O código que define o formato do PIN Block (ex: 01 para ISO-1) não é suportado ou é inválido.
`24` · ***PIN is fewer than 4 or more than 12 digits in length***
A senha (PIN) extraída possui um tamanho não permitido pela norma. Deve ter entre 4 e 12 dígitos.
`25` · ***Decimalization table error***
A tabela de decimalização fornecida (usada em validações de PIN legadas, como IBM3624) contém erros.
`26` · ***Invalid key scheme***
O esquema de chaves (Key Scheme) é inválido para a operação solicitada.
`27` · ***Incompatible key length***
O tamanho da chave é incompatível com a chave de transporte (ex: tentar criptografar uma chave TDES sob uma chave ZMK que é apenas DES simples).
`28` · ***Invalid key type***
O tipo de chave fornecido é inválido.
`29` · ***Key function not permitted***
A função solicitada não é permitida para esta chave específica.
`30` · ***Invalid reference number***
O número de referência da transação é inválido.
`31` · ***Insufficient solicitation entries for batch***
Entradas de solicitação insuficientes para o processamento em lote.
`32` · ***AES not licensed***
O HSM não possui licença para executar operações com o algoritmo AES.
`33` · ***LMK key change storage is corrupted***
O armazenamento de alteração de chaves LMK está corrompido.
`39` · ***Fraud detection***
Detecção de fraude. O HSM bloqueou a transação por anomalias.
***
#### ⚙️ Erros de Hardware, Criptografia e Sistema (40 a 90)
`40` · ***Invalid checksum***
O checksum (KCV) fornecido ou calculado é inválido.
`41` · ***Internal hardware/software error: bad RAM, invalid error codes, etc.***
Erro crítico interno de hardware ou software no HSM.
`42` · ***DES failure***
Falha interna na execução do algoritmo DES.
`43` · ***RSA Key Generation Failure***
Falha ao gerar as chaves assimétricas RSA.
`46` · ***Invalid tag for encrypted PIN***
A tag fornecida para o PIN criptografado é inválida.
`47` · ***Algorithm not licensed***
O algoritmo criptográfico não possui licença ativada no equipamento.
`48` · ***Key cannot be encrypted by a 3DES LMK***
A chave não pode ser criptografada por uma LMK do tipo 3DES.
`49` · ***Private key error, report to supervisor***
Erro na chave privada; contate o administrador do HSM.
`51` · ***Invalid message header***
O cabeçalho da mensagem interna é inválido.
`65` · ***Transaction Key Scheme set to None***
O esquema de chaves da transação foi definido como nulo (None).
`67` · ***Command not licensed***
O HSM não possui licença para executar este comando.
`68` · ***Command has been disabled***
O comando solicitado foi desativado nas configurações do HSM.
`69` · ***PIN block format has been disabled***
O formato de PIN Block solicitado foi desativado (comum em padrões inseguros).
`74` · ***Invalid digest info syntax (no hash mode only)***
Sintaxe de informações de digest inválida.
`75` · ***Single length key masquerading as double or triple length key***
Uma chave de tamanho simples está tentando se passar por uma chave dupla ou tripla.
`76` · ***RSA public key length error or RSA encrypted data length error***
Erro no tamanho da chave pública RSA ou no tamanho dos dados criptografados.
`77` · ***Clear data block error***
Erro no bloco de dados em texto claro.
`78` · ***Private key length error***
Erro no tamanho da chave privada.
`79` · ***Hash algorithm object identifier error***
Erro no identificador do objeto do algoritmo de hash.
`80` · ***Data length error***
A quantidade de dados do MAC (ou outros dados) é maior ou menor do que o esperado.
`81` · ***Invalid certificate header 82 Invalid check value length***
Cabeçalho de certificado inválido ou tamanho do valor de checagem inválido.
`83` · ***Key block format error***
Erro geral de formato no Key Block.
`84` · ***Key block check value error***
Erro no valor de checagem (Check Value) do Key Block.
`85` · ***Invalid OAEP Mask Generation Function***
Função de geração de máscara OAEP inválida.
`86` · ***Invalid OAEP MGF Hash Function***
Função de hash OAEP MGF inválida.
`87` · ***OAEP Parameter Error***
Erro de parâmetro no encapsulamento OAEP.
`90` · ***Data parity error in the request message received by the HSM***
Erro de paridade de dados na mensagem de requisição recebida pelo equipamento.
***
#### 📦 Erros de Blocos de Chaves (Key Blocks / TR-31) (A1 a D3)
`A1` · ***Incompatible LMK schemes***
Os esquemas da LMK são incompatíveis.
`A2` · ***Incompatible LMK identifiers***
Os identificadores da LMK são incompatíveis.
`A3` · ***Incompatible key block LMK identifiers***
Os identificadores da LMK do Key Block são incompatíveis.
`A4` · ***Key block authentication failure***
Falha na autenticação da assinatura/MAC do Key Block.
`A5` · ***Incompatible key length***
O tamanho da chave encapsulada é incompatível.
`A6` · ***Invalid key usage***
O uso pretendido para a chave encapsulada é inválido.
`A7` · ***Invalid algorithm***
O algoritmo definido no Key Block é inválido.
`A8` · ***Invalid mode of use***
O modo de uso (Mode of Use) da chave é inválido.
`A9` · ***Invalid key version number***
O número de versão da chave é inválido.
`AA` · ***Invalid export field***
O campo de controle de exportação é inválido.
`AB` · ***Invalid number of optional blocks***
A quantidade de blocos opcionais informada no cabeçalho é inválida.
`AC` · ***Optional header block error***
Erro no bloco de cabeçalho opcional.
`AD` · ***Key status optional block error***
Erro no bloco opcional de status da chave.
`AE` · ***Invalid start date/time***
A data e hora de início definidas no Key Block são inválidas.
`AF` · ***Invalid end date/time***
A data e hora de término definidas no Key Block são inválidas.
`B0` · ***Invalid encryption mode***
O modo de criptografia (Encryption Mode) é inválido.
`B1` · ***Invalid authentication mode***
O modo de autenticação do bloco é inválido.
`B2` · ***Miscellaneous key block error***
Erro diversificado ou não classificado na estrutura do Key Block.
`B3` · ***Invalid number of optional blocks***
A contagem de blocos opcionais está incorreta.
`B4` · ***Optional block data error***
Os dados contidos em um bloco opcional estão inválidos.
`B5` · ***Incompatible components***
Os componentes da chave fornecidos são incompatíveis.
`B6` · ***Incompatible key status optional blocks***
Os blocos de status de chave opcionais são incompatíveis.
`B7` · ***Invalid change field***
O campo de alteração do bloco está inválido.
`B8` · ***Invalid old value***
O valor antigo (Old Value) fornecido está incorreto.
`B9` · ***Invalid new value***
O novo valor (New Value) fornecido está incorreto.
`BA` · ***No key status block in the key block***
Não foi encontrado o bloco de status da chave dentro do Key Block.
`BB` · ***Invalid wrapping key***
A chave de transporte (Wrapping Key) utilizada é inválida.
`BC` · ***Repeated optional block***
Existe um bloco opcional repetido dentro do pacote.
`BD` · ***Incompatible key types***
Tipos de chaves incompatíveis detectados.
`BE` · ***Invalid key block header ID***
A identificação (ID) do cabeçalho do Key Block é inválida.
`D3` · ***The wrapping key has a lower security strength than the key being wrapped***
**Violação PCI**: A chave de transporte possui uma força de segurança menor que a chave que está sendo protegida.
# Release Notes HoP API V4
### Por que Migrar para a V4
A versão 4 do Hop API não é apenas uma atualização incremental. É uma reescrita dos pontos mais sensíveis da plataforma, endereçando limitações históricas de performance, resiliência e agilidade criptográfica. Abaixo, os benefícios principais que os clientes obtêm ao migrar.
#### 1. Capacidade escalada:
A V4 foi desenhada para ser 10x mais eficiente utilizando o mesmo consumo de recursos, e sem aumento de custo para o cliente.
#### 2. Criptoagilidade
A camada criptográfica foi melhorada. Trocas de algoritmo, atualização de tamanho de chave, adequação a novas exigências PCI e, futuramente, migração para algoritmos pós-quânticos - acontecerão de forma transparente para o código do cliente. Essa é uma das mudanças mais estratégicas da V4: isolar a agilidade criptográfica da First Tech do release cycle da aplicação do cliente.
#### 3. Novo ciclo de homologação PCI HSM
O novo ciclo de homologação PCI HSM acontece exclusivamente sobre a V4. Clientes que dependem da cadeia de certificação PCI para seus próprios processos regulatórios precisam estar na V4 para permanecerem cobertos.
#### 4. Evolução contínua exclusiva
Melhorias de performance e integração com outros serviços First Tech passam a ser entregues apenas na V4.
# Introdução: Módulo EMV
O módulo EMV da plataforma Hop V4 é destinado à validação de ARQC e à geração de ARPC em transações EMV (chip) de crédito e débito.
O módulo EMV da plataforma Hop V4 é destinado à validação de ARQC e à geração de ARPC em transações EMV (chip) de crédito e débito. Este guia fornece as referências técnicas necessárias para o consumo seguro e eficiente das operações criptográficas expostas pela API da First Tech.
### Público-alvo e Pré-requisitos
Este documento é direcionado a desenvolvedores, integradores e arquitetos de sistemas de pagamento que precisam implementar as funcionalidades de validação e geração de criptogramas.
{% hint style="info" %}
**Conhecimento Prévio Necessário**\
Presume-se que o leitor conheça os fundamentos do padrão EMV e compreenda a estrutura de uma mensagem de autorização de pagamento com cartão chip. Termos técnicos específicos utilizados ao longo do texto podem ser consultados diretamente no Glossário.
{% endhint %}
### O que este documento cobre
A documentação está desenhada para cobrir de ponta a ponta a implementação do módulo, englobando:
* **Fundamentos EMV:** Conceitos essenciais relevantes para o uso dos endpoints.
* **Especificação da API:** Detalhamento completo dos endpoints `ValidateARQC4x` e `GenerateARPC4x`.
* **Modelagem de Dados:** Estrutura completa de payloads de requisição e resposta.
* **Regras de Validação:** Matriz de obrigatoriedade condicional de campos de acordo com o modo de operação.
* **Operação e Suporte:** Códigos de erro, estratégias de *troubleshooting*, fluxos de integração e exemplos práticos.
### O que este documento não cobre
Para manter o foco no processamento EMV, os tópicos abaixo não fazem parte deste escopo:
* **Outros Módulos PayShield da Hop V4:** Funcionalidades de Key Manager, Crypto, PIN, CVV, PAN e RSA possuem documentação própria.
* **Autenticação:** O fluxo OAuth2 para emissão de tokens JWT é coberto em um documento separado de autenticação da Hop V4.
* **Onboarding Comercial:** O credenciamento de clientes é conduzido exclusivamente pelos times de pré-vendas e comercial.
* **Especificação Oficial EMVCo:** Este material é um guia de uso do módulo Hop, e não uma referência normativa ao padrão EMV.
# Fundamentos e Fluxo Transacional
Esta seção detalha a base conceitual do padrão EMV, o papel do HSM na infraestrutura de chaves e como a troca de mensagens ocorre na prática durante uma transação.
### O que é EMV?
EMV é o padrão internacional para transações com cartões chip, originalmente estabelecido por Europay, Mastercard e Visa, e atualmente mantido pelo consórcio EMVCo. O padrão especifica as regras de autenticação entre o cartão e o terminal por meio de criptogramas.
### A Necessidade do HSM
O pilar da segurança EMV baseia-se nas Chaves Mestras do Emissor (*Issuer Master Keys*, ou MK), que são armazenadas em hardware criptográfico seguro.
Através destas chaves mestras, o emissor deriva chaves únicas por cartão e por transação. Como as chaves mestras jamais devem ser expostas em texto claro, toda operação de validação ou geração de criptograma precisa ser executada rigorosamente dentro do ambiente criptográfico. O módulo Hop V4 expõe essas operações via API REST, garantindo a manutenção da cadeia PCI HSM de ponta a ponta.
### Os Criptogramas do Fluxo EMV
Em um fluxo típico de autorização, quatro tipos principais de criptogramas podem interagir:
| Sigla | Nome | Significado / Papel no Fluxo |
| -------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **ARQC** | *Authorization Request Cryptogram* | Gerado pelo cartão. Transportado no campo 55 da ISO 8583 (tag 9F26). Indica que o cartão está solicitando autorização online ao emissor. |
| **ARPC** | Authorization Response Cryptogram | Gerado pelo emissor como resposta ao ARQC. Confirma ao cartão que a resposta do emissor é legítima. É justamente o que o endpoint `GenerateARPC4x` produz. |
| **TC** | Transaction Certificate | Gerado pelo cartão ao final de uma transação offline aprovada. Garante a integridade da transação para posterior captura. |
| **AAC** | *Application Authentication Cryptogram* | Gerado pelo cartão quando a transação é negada (offline ou online). Encerra o fluxo EMV. |
## ARQC e ARPC no Fluxo Transacional
Para integrar a API, é necessário compreender onde os endpoints se encaixam em uma autorização típica de crédito ou débito.
### Atores e Sequência de Mensagens
* **Cartão (chip):** Gera o ARQC a partir dos dados da transação e da chave derivada da MK do emissor.
* **Terminal (POS / maquininha):** Monta o campo 55 com as tags EMV e encaminha a autorização para o adquirente.
* **Adquirente e Bandeira:** O adquirente encaminha a autorização para a bandeira, que roteia para o emissor.
* **Emissor (backend):** Recebe a autorização, valida o ARQC via Hop, toma a decisão de autorização e gera o ARPC via Hop para retornar ao cartão.
* **Hop V4 (Módulo EMV):** Atua como HSM-as-a-service que executa a validação e geração de criptogramas com as chaves mestras do emissor.
### Sequência do Fluxo de Autorização Online
O fluxo abaixo apresenta, de forma linear, as trocas entre os atores:
1. O Cartão chip gera o ARQC (tag 9F26) e os dados EMV (campo 55) e envia ao Terminal.
2. O Terminal encaminha a mensagem ISO 8583 com o campo 55 passando pelo Adquirente e pela Bandeira até chegar ao backend do Emissor.
3. O Emissor aciona a Hop V4 (`POST /v4/PayShieldEMV/ValidateARQC4x`) para que o ARQC seja validado contra a chave mestra do cartão .
4. Com a resposta, o Emissor toma a decisão de autorização (aprovar ou negar).
5. O Emissor aciona novamente a Hop V4 (`POST /v4/PayShieldEMV/GenerateARPC4x`) para gerar o ARPC com base no ARC ou CSU.
6. O Emissor devolve a resposta ISO 8583 com o ARPC transportado no campo 55 (tag 91), que trafega pela Bandeira e Adquirente até o Terminal .
7. O Terminal repassa o ARPC e o status ao Cartão, que valida o ARPC e encerra a transação.
{% hint style="info" %}
**Otimização:**
Validar e Gerar em uma Única Chamada É possível combinar as etapas 3 e 5 em uma única chamada ao Hop, utilizando modos de operação que validam o ARQC e já geram o ARPC no mesmo request. Em cenários de alto volume (ex.: autorização de débito em tempo real), combinar validação e geração na mesma chamada (`mode=1,3,5`) tipicamente reduz em aproximadamente metade o tempo total gasto no serviço criptográfico, por evitar o *round-trip* adicional.
{% endhint %}
# Modos de Operação e Bandeiras
Esta página detalha os parâmetros centrais para a correta integração com os endpoints EMV: a escolha do modo de operação (`mode`), o formato do criptograma de resposta (ARC vs CSU) e o mapeamento correto da bandeira do cartão (`schemeId`).
## Modos de Operação
O campo `mode` é o parâmetro central da integração EMV, pois controla exatamente o que o endpoint fará em uma única chamada. Entender os modos disponíveis evita o envio de requisições com dados faltantes e chamadas desnecessárias ao HSM.
### Tabela de Modos Disponíveis
A tabela abaixo relaciona o valor do `mode`, a operação que ele executa e qual método de ARPC é utilizado:
| mode | O que faz | Método ARPC Utilizado |
| ---- | --------------------------------------------------------------- | --------------------- |
| 0 | Validar ARQC apenas. | - |
| 1 | Validar ARQC e gerar ARPC. | Método 1 - ARC |
| 2 | Gerar ARPC sem validar ARQC. | Método 1 - ARC |
| 3 | Validar ARQC e gerar ARPC. | Método 2 - CSU |
| 4 | Gerar ARPC sem validar ARQC. | Método 2 - CSU |
| 5 | Validar ARQC e gerar ARPC (ambos os métodos simultaneamente). | Métodos 1 e 2 |
| 6 | Gerar ARPC sem validar ARQC (ambos os métodos simultaneamente). | Métodos 1 e 2 |
| 8 | Validar TC ou AAC (encerramento de transação offline). | - |
| 9 | Validar TC/AAC e gerar ARPC. | Método 1 - ARC |
### Método 1 (ARC) vs Método 2 (CSU)
A diferença fundamental entre os métodos de geração de ARPC está na forma como a resposta do emissor é codificada no criptograma :
* **Método 1 — ARC (Authorization Response Code):** Utiliza o campo `arc`, que consiste em um par de bytes em hexadecimal codificando a resposta do emissor segundo a tabela padrão ISO 8583 (tag 8A) . **Exemplos comuns:** `00` = aprovado, `01` = referir, `05` = negado. É o formato mais amplamente utilizado em fluxos tradicionais de autorização.
* **Método 2 — CSU (Card Status Update):** Utiliza o campo `csu`, composto por quatro bytes em hexadecimal que fornecem informações estendidas sobre o status do cartão, além da própria resposta de autorização .
{% hint style="warning" %}
#### **Quando usar cada método**
* Utilize `mode=1` (ARC) para a maioria das autorizações convencionais, especialmente em fluxos legados ou quando o `schemeId` for do tipo VIS (`0`) ou M/Chip CVN 10/11 (`1`) .
* Utilize `mode=3` (CSU) quando o `schemeId` indicar M/Chip Advance, Visa qVSDC (`9`) ou esquemas mais modernos.
* Utilize `mode=5` (Ambos) apenas quando a arquitetura do emissor exigir a resposta simultânea em ambos os formatos.
{% endhint %}
### Obrigatoriedade Condicional de `arc` e `csu`
A API valida se os campos `arc` e `csu` foram enviados dependendo estritamente do `mode` escolhido. O não envio gerará falha na requisição:
| mode | arc | cs |
| ----- | ------------------------------------------------ | ------------------------------------------------ |
| **0** | Ignorado | Ignorado |
| **1** | Obrigatório | Ignorado |
| **2** | Obrigatório | Ignorado |
| **3** | Ignorado | Obrigatório |
| **4** | Ignorado | Obrigatório |
| **5** | Obrigatório | Obrigatório |
| **6** | Obrigatório | Obrigatório |
| **9** | Obrigatório | Ignorado |
## Scheme ID e Bandeiras Suportadas
O campo `schemeId` identifica a variante do esquema criptográfico EMV que o cartão utiliza. Note que o mesmo número de cartão (PAN) pode estar vinculado a esquemas diferentes dependendo da bandeira, versão e do CVN (Cryptogram Version Number).
### Tabela de Scheme IDs
schemeId
Esquema
Observações
0
Visa VIS (CVN 10 ou 17)
Esquema Visa tradicional, amplamente utilizado em crédito e débito Visa.
1
Mastercard M/Chip (CVN 10 ou 11)
Esquema Mastercard tradicional.
2
American Express AEIPS
Esquema proprietário American Express.
3
Mastercard M/Chip com PAN length
Variação do esquema M/Chip que inclui o tamanho do PAN no cálculo.
5
Visa VIS com PAN length
Variação do esquema VIS que inclui o tamanho do PAN.
6
JCB
Esquema JCB.
7
Discover
Esquema Discover.
9
Visa qVSDC
Esquema Visa contactless, típico de transações sem contato e tokenizadas.
A
Mastercard PayPass
Esquema Mastercard contactless (PayPass).
{% hint style="info" %}
#### Relação entre Brand e Scheme ID:
O campo `brand` aceita exclusivamente os valores `MASTERCARD`, `VISA` e `AMEX`, sendo utilizado para a seleção do perfil mestre no HSM. O `schemeId`, por sua vez, atua como um refinamento da variante criptográfica.
**Nota sobre outras bandeiras:** Embora a tabela de `schemeId` suporte esquemas como JCB (6) e Discover (7), e existam menções comerciais a bandeiras como Elo e Hipercard, esses nomes não são valores válidos atualmente para o campo `brand` na requisição. É fundamental garantir que a combinação enviada entre o `brand` (limitado aos três valores aceitos) e o `schemeId` seja consistente com o cartão para evitar erros de validação.
{% endhint %}
# Referência da API - EMV
Esta secção apresenta a especificação técnica completa para o consumo dos endpoints do módulo EMV da Hop V4.
## Autenticação e Base URL
Todos os endpoints do módulo EMV da Hop V4 exigem um token Bearer obtido via OAuth2 (`grant_type: client_credentials`). O token é transportado no cabeçalho `Authorization` em toda a requisição.
### Configurações de Conexão:
Parâmetro
Valor
Base URL (API)
https://apivin.first-tech.net[A confirmar host definitivo de PRD/HML]
Endpoint de autenticação
https://auth.first-tech.net/oauth/token
grant_type
client_credentials
audience
https://auth-jwt-authorize-prd-first-tech
token_type
Bearer
Tempo de vida (padrão)
[A confirmar TTL do token com a equipa técnica]
### Cabeçalhos Obrigatórios (`Headers`):
```http
HTTP
Authorization: Bearer
Content-Type: application/json
Accept: */*
```
{% hint style="info" %}
#### Estratégia de Renovação de Token:
Recomenda-se renovar o token antes da expiração, mantendo um *cache* no lado do cliente. Evite solicitar um novo token a cada chamada EMV, pois isso adiciona latência desnecessária e onera o serviço de autenticação . Em caso de resposta HTTP `401`, descarte o token em *cache*, solicite um novo e reenvie a requisição.
{% endhint %}
### POST /ValidateARQC4x
## Validar ARQC (Request Cryptogram)
> Valida o ARQC (Authorization Request Cryptogram) recebido no campo 55 da transação EMV.\
> Retorna \`true\` em \`retValid\` se o ARQC for válido, \`false\` caso contrário.\
> Retorna o ARPC gerado em \`retValue\` em formato Hex.\
> \
> O campo \`field55EmvTags\` deve conter os dados EMV da transação em formato TLV hexadecimal.\
> O ARQC é extraído automaticamente da tag \`9F26\` do campo 55.\
> \
> Em caso de erro, retorna os campos de erro (\`retCode\` e \`retDesc\`).
```json
{"openapi":"3.0.3","info":{"title":"PayShield EMV API","version":"4.1.32"},"tags":[{"name":"EMV","description":"Operações de geração e validação de criptogramas EMV (ARPC/ARQC)"}],"servers":[{"url":"https://apivin.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"ArpcInput":{"type":"object","required":["client_id","brand","mode","schemeId","mkacKeyId","pan","panSeqNr","field55EmvTags"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"brand":{"type":"string","enum":["MASTERCARD","VISA","AMEX"],"description":"Bandeira do cartão"},"mode":{"type":"string","description":"Modo de operação do comando EMV:\n- `0`: Validar ARQC\n- `1`: Validar ARQC e gerar ARPC método 1 (ARC)\n- `2`: Gerar ARPC método 1 (ARC) sem validar ARQC\n- `3`: Validar ARQC e gerar ARPC método 2 (CSU)\n- `4`: Gerar ARPC método 2 (CSU) sem validar ARQC\n- `5`: Validar ARQC e gerar ARPC métodos 1 e 2\n- `6`: Gerar ARPC métodos 1 e 2 sem validar ARQC\n- `8`: Validar TC/AAC\n- `9`: Validar TC/AAC e gerar ARPC método 1\n"},"schemeId":{"type":"string","description":"Identificador do esquema EMV:\n- `0`: Visa VIS (CVN 10 ou 17)\n- `1`: Mastercard M/Chip (CVN 10 ou 11)\n- `2`: American Express AEIPS\n- `3`: Mastercard M/Chip com PAN length\n- `5`: Visa VIS com PAN length\n- `6`: JCB\n- `7`: Discover\n- `9`: Visa qVSDC\n- `A`: Mastercard PayPass\n- `B`: Mastercard PayPass com PAN length\n- `C`: Mastercard PayPass com padding flag\n"},"iv_ac":{"type":"string","nullable":true,"description":"IV para derivação de chave de sessão EMV 2000.\nObrigatório apenas para `schemeId` = `0` ou `1`.\n"},"branch_height_params":{"type":"string","nullable":true,"description":"Parâmetros de branch/height para derivação de chave de sessão EMV 2000.\nObrigatório apenas para `schemeId` = `0` ou `1`.\n- `0`: Branch factor 2, Tree Height 16\n- `1`: Branch factor 4, Tree Height 8\n"},"mkacKeyId":{"type":"string","description":"Alias/identificador da chave MKAC no banco de dados"},"pan":{"type":"string","description":"PAN do cartão"},"panSeqNr":{"type":"string","description":"Número de sequência do PAN (PSN) — usar `00` se não disponível"},"field55EmvTags":{"type":"string","description":"Dados EMV da transação em formato TLV hexadecimal (campo 55 da ISO 8583).\nO ARQC é extraído automaticamente da tag `9F26`.\nTags relevantes utilizadas: `9F26` (ARQC), `9F36` (ATC), `9F10` (Issuer Application Data), `8C` (CDOL1).\n"},"arc":{"type":"string","nullable":true,"description":"Authorization Response Code — obrigatório para `mode` = `1`, `2`, `5`, `6` ou `9`.\nValor em Hex (ex: `00` = aprovado, `01` = negado).\n"},"arqc":{"type":"string","nullable":true,"description":"ARQC (Authorization Request Cryptogram) em Hex.\nQuando informado, sobrescreve o valor extraído automaticamente da tag `9F26` do `field55EmvTags`.\nUtilizado principalmente no endpoint `ValidateARQC4x`.\n"},"csu":{"type":"string","nullable":true,"description":"Card Status Update — obrigatório para `mode` = `3`, `4`, `5` ou `6`.\n4 bytes em Hex.\n"}}},"ReturnSingle":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","nullable":true,"description":"ARPC gerado em Hex (quando aplicável)"},"retValid":{"type":"boolean","description":"Indica se o ARQC foi validado com sucesso"},"retDescription":{"type":"string"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `01`: Falha na verificação do ARQC/TC/AAC/MPVV\n- `03`: Padding Flag inválido\n- `04`: Mode Flag não reconhecido\n- `05`: Scheme ID não reconhecido\n- `06`: Valor YHHHHCC inválido\n- `10`: Erro de paridade na chave MK\n- `52`: Branch/Height inválido\n- `68`: Comando desabilitado\n- `F1`: Método de derivação de chave inválido\n- `F2`: Método de validação ARQC inválido\n- `F3`: Algoritmo da chave MK-AC não é AES\n- `F5`: Método de chave de sessão inválido\n- `F8`: Método de geração de chave OTPK inválido\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDesc":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldEMV/ValidateARQC4x":{"post":{"tags":["EMV"],"summary":"Validar ARQC (Request Cryptogram)","description":"Valida o ARQC (Authorization Request Cryptogram) recebido no campo 55 da transação EMV.\nRetorna `true` em `retValid` se o ARQC for válido, `false` caso contrário.\nRetorna o ARPC gerado em `retValue` em formato Hex.\n\nO campo `field55EmvTags` deve conter os dados EMV da transação em formato TLV hexadecimal.\nO ARQC é extraído automaticamente da tag `9F26` do campo 55.\n\nEm caso de erro, retorna os campos de erro (`retCode` e `retDesc`).\n","operationId":"validateARQC4x","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArpcInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnSingle"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"404":{"description":"Chave não encontrada no banco de dados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
### POST /GenerateARPC4x
## Gerar ARPC (Response Cryptogram)
> Gera o ARPC (Authorization Response Cryptogram) a partir do ARQC recebido no campo 55 da transação EMV.\
> Retorna o ARPC gerado em \`retMultiValue\[0]\` em formato Hex.\
> \
> O campo \`field55EmvTags\` deve conter os dados EMV da transação em formato TLV hexadecimal.\
> Os campos \`arc\` e \`csu\` são utilizados dependendo do \`mode\` de operação.\
> \
> Em caso de erro, retorna os campos de erro (\`retCode\` e \`retDesc\`).
```json
{"openapi":"3.0.3","info":{"title":"PayShield EMV API","version":"4.1.32"},"tags":[{"name":"EMV","description":"Operações de geração e validação de criptogramas EMV (ARPC/ARQC)"}],"servers":[{"url":"https://apivin.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"ArpcInput":{"type":"object","required":["client_id","brand","mode","schemeId","mkacKeyId","pan","panSeqNr","field55EmvTags"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"brand":{"type":"string","enum":["MASTERCARD","VISA","AMEX"],"description":"Bandeira do cartão"},"mode":{"type":"string","description":"Modo de operação do comando EMV:\n- `0`: Validar ARQC\n- `1`: Validar ARQC e gerar ARPC método 1 (ARC)\n- `2`: Gerar ARPC método 1 (ARC) sem validar ARQC\n- `3`: Validar ARQC e gerar ARPC método 2 (CSU)\n- `4`: Gerar ARPC método 2 (CSU) sem validar ARQC\n- `5`: Validar ARQC e gerar ARPC métodos 1 e 2\n- `6`: Gerar ARPC métodos 1 e 2 sem validar ARQC\n- `8`: Validar TC/AAC\n- `9`: Validar TC/AAC e gerar ARPC método 1\n"},"schemeId":{"type":"string","description":"Identificador do esquema EMV:\n- `0`: Visa VIS (CVN 10 ou 17)\n- `1`: Mastercard M/Chip (CVN 10 ou 11)\n- `2`: American Express AEIPS\n- `3`: Mastercard M/Chip com PAN length\n- `5`: Visa VIS com PAN length\n- `6`: JCB\n- `7`: Discover\n- `9`: Visa qVSDC\n- `A`: Mastercard PayPass\n- `B`: Mastercard PayPass com PAN length\n- `C`: Mastercard PayPass com padding flag\n"},"iv_ac":{"type":"string","nullable":true,"description":"IV para derivação de chave de sessão EMV 2000.\nObrigatório apenas para `schemeId` = `0` ou `1`.\n"},"branch_height_params":{"type":"string","nullable":true,"description":"Parâmetros de branch/height para derivação de chave de sessão EMV 2000.\nObrigatório apenas para `schemeId` = `0` ou `1`.\n- `0`: Branch factor 2, Tree Height 16\n- `1`: Branch factor 4, Tree Height 8\n"},"mkacKeyId":{"type":"string","description":"Alias/identificador da chave MKAC no banco de dados"},"pan":{"type":"string","description":"PAN do cartão"},"panSeqNr":{"type":"string","description":"Número de sequência do PAN (PSN) — usar `00` se não disponível"},"field55EmvTags":{"type":"string","description":"Dados EMV da transação em formato TLV hexadecimal (campo 55 da ISO 8583).\nO ARQC é extraído automaticamente da tag `9F26`.\nTags relevantes utilizadas: `9F26` (ARQC), `9F36` (ATC), `9F10` (Issuer Application Data), `8C` (CDOL1).\n"},"arc":{"type":"string","nullable":true,"description":"Authorization Response Code — obrigatório para `mode` = `1`, `2`, `5`, `6` ou `9`.\nValor em Hex (ex: `00` = aprovado, `01` = negado).\n"},"arqc":{"type":"string","nullable":true,"description":"ARQC (Authorization Request Cryptogram) em Hex.\nQuando informado, sobrescreve o valor extraído automaticamente da tag `9F26` do `field55EmvTags`.\nUtilizado principalmente no endpoint `ValidateARQC4x`.\n"},"csu":{"type":"string","nullable":true,"description":"Card Status Update — obrigatório para `mode` = `3`, `4`, `5` ou `6`.\n4 bytes em Hex.\n"}}},"ReturnMultiValue":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","nullable":true},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Array com os valores de retorno — `retMultiValue[0]` contém o ARPC gerado em Hex"},"retValid":{"type":"boolean"},"retDesc":{"type":"string"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `01`: Falha na verificação do ARQC/TC/AAC/MPVV\n- `03`: Padding Flag inválido\n- `04`: Mode Flag não reconhecido\n- `05`: Scheme ID não reconhecido\n- `06`: Valor YHHHHCC inválido\n- `10`: Erro de paridade na chave MK\n- `52`: Branch/Height inválido\n- `68`: Comando desabilitado\n- `F1`: Método de derivação de chave inválido\n- `F2`: Método de validação ARQC inválido\n- `F3`: Algoritmo da chave MK-AC não é AES\n- `F5`: Método de chave de sessão inválido\n- `F8`: Método de geração de chave OTPK inválido\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDesc":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldEMV/GenerateARQC4x":{"post":{"tags":["EMV"],"summary":"Gerar ARPC (Response Cryptogram)","description":"Gera o ARPC (Authorization Response Cryptogram) a partir do ARQC recebido no campo 55 da transação EMV.\nRetorna o ARPC gerado em `retMultiValue[0]` em formato Hex.\n\nO campo `field55EmvTags` deve conter os dados EMV da transação em formato TLV hexadecimal.\nOs campos `arc` e `csu` são utilizados dependendo do `mode` de operação.\n\nEm caso de erro, retorna os campos de erro (`retCode` e `retDesc`).\n","operationId":"generateARQC4x","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArpcInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnMultiValue"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"404":{"description":"Chave não encontrada no banco de dados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
## Modelos de Objeto
Esta seção detalha os modelos de objeto utilizados pelos endpoints EMV. Todos os modelos seguem a convenção de nomenclatura adotada na Hop V4.
### Arpcinput (Modelo de Request)
Modelo único de request, utilizado por ambos os endpoints.
Campo
Tipo
Obrigatório
Observação
client_id
integer (int64, min 1)
Sim
Identificador do cliente.
brand
string (enum)
Sim
MASTERCARD, VISA ou AMEX.
mode
string
Sim
Modo de operação — ver seção 4.
schemeId
string
Sim
Esquema EMV — ver seção 5.
iv_ac
string (nullable)
Não
IV do AC — null quando não aplicável.
branch_height_params
string (nullable)
Não
Parâmetros de árvore de chaves.
mkacKeyId
string
Sim
Identificador da chave MK-AC do emissor.
pan
string
Sim
Primary Account Number.
panSeqNr
string
Sim
PSN — usar "00" se não disponível.
field55EmvTags
string
Sim
Campo 55 em TLV hexadecimal.
arc
string (nullable)
Condicional
Obrigatório para mode = 1, 2, 5, 6, 9.
csu
string (nullable)
Condicional
Obrigatório para mode = 3, 4, 5, 6.
arqc
string (nullable)
Não
Sobrescreve o ARQC da tag 9F26.
### Modelos de Resposta (Responses)
#### ReturnSingle (Response de `ValidateARQC4x` com sucesso):
* `retCode` (integer):
`0` indica sucesso.
* `retValue` (string):
ARPC gerado em hexadecimal (modos de validação + geração).
* `retValid` (boolean):
`true` se validado com sucesso.
* `retDescription` (string):
Descrição textual do resultado.
#### ReturnMultiValue (Response de `GenerateARPC4x` com sucesso):
* `retCode` (integer): `0` indica sucesso.
* `retValue` (string): Sempre vazio em caso de sucesso.
* `retMultiValue` (string\[]): Array; `retMultiValue[0]` contém o ARPC gerado.
* `retValid` (boolean): Indica operação bem-sucedida.
* `retDesc` (string): Descrição textual do resultado.
ReturnError (Response de Erro - 400, 404, 500) :
* `retCode` (integer): Código de erro específico (ver taxonomia).
* `retValue` (string): Não utilizado.
* `retMultiValue` (any): Não utilizado.
* `retValid` (boolean): `false` em erros.
* `retDesc` (string): Descrição textual do erro
# 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:
retCode
Significado
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) 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`
Sintoma Observado
Causa Provável
Ação Sugerida
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.
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_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"
}
```
# Apêndices
Esta secção contém materiais de consulta rápida e referências normativas que auxiliam na compreensão dos dados processados pelo módulo EMV e no entendimento da terminologia técnica utilizada.
### Apêndice A. Tags EMV (Campo 55) Relevantes
As tags listadas abaixo são as mais relevantes para a integração com o módulo. Todas elas trafegam no payload dentro do campo `field55EmvTags`, codificadas no formato TLV (Tag-Length-Value) em hexadecimal .
Tag
Nome
Descrição Técnica
9F26
Application Cryptogram
O ARQC propriamente dito (8 bytes). É extraído automaticamente pelos endpoints EMV.
9F36
Application Transaction Counter (ATC)
Contador sequencial de transações do cartão (2 bytes). Utilizado na derivação da chave de sessão.
9F10
Issuer Application Data (IAD)
Dados proprietários do emissor usados na verificação do ARQC. O tamanho é variável dependendo da bandeira e CVN.
8C
CDOL1
Card Risk Management Data Object List 1. Lista de tags que o cartão solicitou ao terminal para gerar o ARQC.
9F02
Amount, Authorised
Valor da transação autorizada, em centavos, formato de 12 dígitos BCD.
5F2A
Transaction Currency Code
Código ISO 4217 numérico da moeda (ex.: 986 para BRL).
9A
Transaction Date
Data da transação no formato YYMMDD (3 bytes).
9C
Transaction Type
Código do tipo de transação (00 = compra, 01 = compra com cashback, 20 = refund).
91
Issuer Authentication Data
Tag na qual o ARPC é transportado de volta ao cartão. Tipicamente contém o ARPC (8 bytes) + ARC (2 bytes) ou ARPC + CSU.
{% hint style="info" %}
Referência Normativa\
A especificação EMV completa sobre as tags está disponível no documento EMV 4.x, Book 3 — Application Specification, publicado pela EMVCo . Para particularidades de cada bandeira, consulte também os cadernos proprietários (ex.: Visa VIS, Mastercard M/Chip Requirements).
{% endhint %}
### Apêndice B. Glossário
Dicionário de siglas e termos técnicos que aparecem ao longo da documentação da Hop V4 .
Termo / Sigla
Definição
AAC
Application Authentication Cryptogram. Criptograma gerado pelo cartão quando a transação é recusada.
AES
Advanced Encryption Standard. Algoritmo simétrico usado em esquemas EMV modernos.
ARC
Authorization Response Code. Código de 2 bytes em hexadecimal que representa a resposta do emissor (ex.: 00 = aprovado, 05 = negado). Usado no método 1 de ARPC.
ARPC
Authorization Response Cryptogram. Criptograma gerado pelo emissor em resposta ao ARQC.
ARQC
Authorization Request Cryptogram. Criptograma gerado pelo cartão no início da autorização online.
ATC
Application Transaction Counter. Contador sequencial do cartão, incrementado a cada transação.
BIN
Bank Identification Number. Primeiros 6 a 8 dígitos do PAN, que identificam o emissor e o produto.
CDOL1
Card Risk Management Data Object List 1. Lista de tags que o cartão solicita do terminal para gerar o ARQC.
CSU
Card Status Update. Campo de 4 bytes em hexadecimal que representa a resposta do emissor no método 2 de ARPC.
CVN
Cryptogram Version Number. Versão do esquema criptográfico usado pelo cartão.
EMV
Padrão internacional para transações com cartões chip, mantido pela EMVCo.
EMVCo
Consórcio mantenedor do padrão EMV, composto por Amex, Discover, JCB, Mastercard, UnionPay e Visa.
HSM
Hardware Security Module. Dispositivo dedicado para armazenamento e uso de chaves criptográficas.
IAD
Issuer Application Data. Tag 9F10 — dados proprietários do emissor usados na verificação do ARQC.
ISO 8583
Padrão internacional de mensageria para transações de cartão de pagamento.
JWT
JSON Web Token. Formato do token emitido pelo OAuth2 e usado no cabeçalho Authorization.
MK-AC
Master Key for Application Cryptogram. Chave mestra do emissor usada para derivar a chave de sessão do cartão.
MPVV
Mastercard PIN Verification Value. Algoritmo proprietário Mastercard para verificação de PIN.
OAuth2
Protocolo de autorização. A Hop V4 utiliza o fluxo client_credentials.
OTPK
One-Time Pin Key. Chave de uso único em alguns esquemas.
PAN
Primary Account Number. Número do cartão.
PCI HSM
Padrão do PCI Security Standards Council para HSMs que processam dados de cartão.
PIN
Personal Identification Number.
PSN
PAN Sequence Number. Identifica aplicações adicionais no mesmo cartão.
qVSDC
Quick Visa Smart Debit/Credit. Esquema contactless da Visa.
Scheme ID
Identificador do esquema criptográfico EMV utilizado pelo cartão.
TC
Transaction Certificate. Criptograma gerado pelo cartão ao final de uma transação offline aprovada.
TLV
Tag-Length-Value. Formato de codificação usado em EMV para estruturar os dados do campo 55.
VIS
Visa Integrated Circuit Card Specification. Esquema tradicional Visa.
# Introdução e Fundamentos
### Módulo Crypto
O módulo PayShield Crypto da plataforma Hop V4 oferece um conjunto de operações criptográficas simétricas executadas integralmente dentro do HSM (Hardware Security Module) gerenciado pela First Tech. A principal premissa deste serviço é garantir que o material de chave nunca deixe a fronteira segura do hardware.
Este documento fornece ao integrador a referência técnica completa, englobando fundamentos, modelos de dados, fluxo de integração, casos de uso práticos e taxonomia de erros.
### Público-Alvo e Pré-requisitos
Esta documentação é desenhada para:
* Desenvolvedores que integram aplicações ou *hosts* ao Hop V4.
* Arquitetos que avaliam o uso de criptografia gerenciada como serviço.
* Times de Segurança da Informação responsáveis por validar o desenho criptográfico da solução.
#### Pré-requisitos de Integração
Para consumir os endpoints descritos neste guia, certifique-se de que o seu ambiente cumpre os seguintes requisitos:
1. Cliente provisionado na plataforma Hop V4, com um `client_id` atribuído.
2. Pelo menos uma chave criptográfica cadastrada e associada ao seu `client_id`, com o respectivo alias (`keyId`) conhecido.
3. Credenciais Auth0 (token JWT) válidas para o ambiente de destino.
4. Conectividade de rede autorizada para o endpoint `apivin.first-tech.net`.
### Fundamentos do PayShield Crypto
#### Operações Suportadas
O serviço expõe quatro famílias principais de operações criptográficas simétricas:
1. Cifragem de dados (`EncryptData`): Proteção de informações sensíveis para armazenamento seguro ou trânsito.
2. Decifragem de dados (`DecryptData` e `SuperDecryptData`): Recuperação do conteúdo original em texto claro (incluindo suporte a múltiplos blocos).
3. Geração de MAC (`GenerateMac`): Produção de um código de autenticação (Message Authentication Code) para garantir a integridade e autenticidade de mensagens.
4. Validação de MAC (`ValidateMac`): Verificação da integridade e autenticidade do código gerado.
#### Princípio Operacional e Algoritmos
Toda operação criptográfica atua sobre uma chave referenciada pelo seu `keyId`, que funciona como um alias armazenado no banco de dados gerenciado pela First Tech. O material criptográfico real nunca trafega pela API. A sua aplicação envia apenas o identificador da chave e os dados a serem processados; o HSM executa o cálculo e o resultado retorna em formato hexadecimal .
O algoritmo simétrico aplicado (como DES, 3DES ou AES) é determinado automaticamente pelo tipo da chave que foi provisionada. O integrador não precisa enviar o algoritmo no payload; o seu controle resume-se à escolha do modo de operação através do campo `modeEncFlag`
#### Modelo Padrão de Chamada
Para garantir consistência na integração, todos os endpoints do módulo Crypto seguem o mesmo contrato base:
* **Método HTTP:** `POST`.
* **Autenticação:** Bearer Token (JWT obtido via Auth0).
* **Content-Type:** `application/json`.
* **Identificação do Tenant:** Informada obrigatoriamente no campo `client_id` do corpo da requisição (*body*).
* **Identificação da Chave:** Informada no campo `keyId` do *body*.
* **Resposta Padronizada:** Os objetos de retorno sempre conterão os campos `retCode`, `retValue`, `retMultiValue`, `retValid` e `retDesc`.
# Modos de Operação e Retornos
Para integrar com sucesso o módulo PayShield Crypto, é fundamental compreender como a API encadeia os dados durante a cifragem/decifragem e como os objetos de retorno são estruturados.
### Modos de Operação (`modeEncFlag`)
Os modos de operação determinam como blocos sucessivos de dados são encadeados durante a cifragem ou decifragem. A escolha do modo impacta diretamente os requisitos de envio do Vetor de Inicialização (IV) e a resistência da criptografia a determinados ataques.
#### Tabela de Modos Suportados
Código (modeEncFlag)
Modo
IV Obrigatório?
Característica Principal
00
ECB
Não
Padrão se o campo for null ou ausente. Cada bloco é cifrado independentemente. Não recomendado para dados estruturados.
01
CBC
Sim
Encadeia blocos via XOR com o cifrado anterior. É o padrão de mercado para dados em repouso.
02
CFB8
Sim
Cifra o fluxo em janelas de 8 bits. Adequado para dados de comprimento arbitrário.
03
CFB64
Sim
Variante do CFB com janela de 64 bits.
#### Regras do Vetor de Inicialização (IV)
* Quando é obrigatório: Nos modos `01` (CBC), `02` (CFB8) e `03` (CFB64), o campo `iv` tem de ser enviado na requisição obrigatoriamente. No modo `00` (ECB), pode ser omitido ou enviado como `null`.
* Geração e Formato: O valor deve ser expresso em hexadecimal e tem de ser único por operação (nunca reutilize IVs entre transações com a mesma chave).
* Retorno em Cifragem: Nas operações de `EncryptData` que exigem IV, o vetor utilizado é refletido na resposta através do campo `retMultiValue[1]` (como `ivResp`). Esse valor retornado deve ser armazenado, pois será obrigatório como entrada na decifragem subsequente.
#### Uso de Chaves Derivadas (DUKPT)
Quando a chave referenciada pelo campo `keyId` for do tipo BDK (*Base Derivation Key*), a API passa a exigir parâmetros de DUKPT (*Derived Unique Key Per Transaction*). Neste cenário, os campos `ksn_desc` e `ksn` tornam-se obrigatórios na requisição. A plataforma Hop encarrega-se de derivar a chave de transação correspondente ao KSN informado e utilizá-la para a operação solicitada.
### Mensagem de Retorno
Todos os endpoints da API Crypto retornam o mesmo "envelope" de resposta padronizado.
#### Estrutura Base do Response
Campo
Tipo
Significado
retCode
integer
Código numérico de retorno. 0 indica sucesso; valores diferentes de zero indicam erro (ver secção de códigos de erro).
retValue
string
Valor de retorno simples. Em operações Crypto, geralmente vem vazio (este campo é mais utilizado noutros módulos PayShield).
retMultiValue
array
Valores estruturados da operação. O conteúdo deste array varia de acordo com o endpoint acionado (ver tabela abaixo).
retValid
boolean
Indica se a operação foi bem-sucedida. No endpoint ValidateMac, indica também se o MAC analisado é válido.
retDesc
string
Descrição textual do resultado. Retorna "OK" em caso de sucesso; ou uma mensagem detalhada em caso de erro.
#### `retMultiValue` por Endpoint
O "coração" da resposta em criptografia reside no campo `retMultiValue`. Ele comporta-se de maneira diferente conforme a operação:
Endpoint
Posição [0]
EncryptData
msgRespEncrypted (Hexadecimal)
ivResp (Hexadecimal). Retorna apenas nos modos 01, 02 ou 03.
DecryptData
msgRespDecrypted (Hexadecimal)
ivResp (Hexadecimal). Retorna apenas nos modos 01, 02 ou 03.
SuperDecryptData
Array de arrays — Cada item do lote segue estritamente o formato de resposta do DecryptData.
-
GenerateMac
mac gerado (Hexadecimal)
ivResp — Apenas quando macModeFlag for 1 ou 2 (encadeamento multi-bloco).
ValidateMac
Confirmação do MAC (echo)
ivResp — Apenas quando macModeFlag for 1 ou 2.
# Referência da API - CRYPTO
Esta página detalha os endpoints responsáveis pela proteção (cifragem) e recuperação (decifragem) de dados, incluindo a operação de decifragem em lote (*SuperDecryptData*).
### Autenticação
Todas as chamadas para os endpoints do módulo Crypto exigem o cabeçalho `Authorization` preenchido com um token Bearer JWT válido.
#### Exemplo de Cabeçalho:
```http
HTTP
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ii4uLiJ9...
```
## Criptografar dados
> Retorna os dados criptografados e o IV (se aplicável) em formato Hex.\
> Em caso de erro, retorna os campos de erro (retCode e retDescription).\
> \
> Retorna em \`retMultiValue\`:\
> \- \`retMultiValue\[0]\` = msgRespEncrypted → Mensagem criptografada\
> \- \`retMultiValue\[1]\` = ivResp → IV para a próxima chamada de descriptografia,\
> apenas nos modos modeEncFlag 01, 02, 03. Caso contrário, será null.
```json
{"openapi":"3.0.3","info":{"title":"PayShield Crypto API","version":"4.1.32"},"tags":[{"name":"Crypto","description":"Operações de criptografia e descriptografia de dados"}],"servers":[{"url":"https://api-research.first-tech.net/qseed","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"EncryptDataInput":{"allOf":[{"$ref":"#/components/schemas/CryptoInputBase"},{"type":"object","required":["p_ht_data"],"properties":{"p_ht_data":{"type":"string","description":"Dados a serem criptografados em formato H (Hex) ou T (Texto)"},"b_data":{"type":"string","nullable":true,"description":"Dados em formato binário (uso reservado)"}}}]},"CryptoInputBase":{"type":"object","required":["client_id","keyId","modeEncFlag","data_fmt"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave no banco de dados"},"modeEncFlag":{"type":"string","description":"Modo de operação da cifra:\n- `00`: ECB (padrão se null ou valor não listado)\n- `01`: CBC (requer IV)\n- `02`: CFB8 (requer IV)\n- `03`: CFB64 (requer IV)\n"},"ksn_desc":{"type":"string","nullable":true,"description":"Descritor KSN — necessário apenas se o keyId for do tipo BDK (DUKPT)"},"ksn":{"type":"string","nullable":true,"description":"KSN — necessário apenas se o keyId for do tipo BDK (DUKPT)"},"iv":{"type":"string","nullable":true,"description":"Vetor de inicialização em Hex — obrigatório nos modos 01, 02, 03"},"data_fmt":{"type":"string","enum":["H","T"],"description":"Formato dos dados de entrada:\n- `H`: Hexadecimal\n- `T`: Texto\n"}}},"ReturnMultiValue":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","description":"Valor de retorno simples (geralmente vazio em sucesso)"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com os valores de retorno da operação"},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retDesc":{"type":"string","description":"Descrição do resultado"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `-1`: Erro interno\n- `-2`: Formato inválido\n- `137`: Malformação da requisição\n- `155`: Chave não encontrada no banco de dados\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDesc":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/demo/generate":{"post":{"tags":["Crypto"],"summary":"Criptografar dados","description":"Retorna os dados criptografados e o IV (se aplicável) em formato Hex.\nEm caso de erro, retorna os campos de erro (retCode e retDescription).\n\nRetorna em `retMultiValue`:\n- `retMultiValue[0]` = msgRespEncrypted → Mensagem criptografada\n- `retMultiValue[1]` = ivResp → IV para a próxima chamada de descriptografia,\n apenas nos modos modeEncFlag 01, 02, 03. Caso contrário, será null.\n","operationId":"encryptData","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EncryptDataInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnMultiValue"}}}},"400":{"description":"Requisição inválida (campo obrigatório ausente ou formato incorreto)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"404":{"description":"Chave não encontrada no banco de dados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
***
## Descriptografar dados
> Retorna os dados descriptografados e o IV (se aplicável) em formato Hex.\
> Em caso de erro, retorna os campos de erro (retCode e retDescription).\
> \
> Retorna em \`retMultiValue\`:\
> \- \`retMultiValue\[0]\` = msgRespDecrypted → Mensagem descriptografada\
> \- \`retMultiValue\[1]\` = ivResp → IV para a próxima chamada de criptografia,\
> apenas nos modos modeEncFlag 01, 02, 03. Caso contrário, será null.\
> \
> O campo \`data\_fmt\` aceita apenas \`H\` (Hexadecimal) ou \`T\` (Texto). O formato \`B\` não é suportado.
```json
{"openapi":"3.0.3","info":{"title":"PayShield Crypto API","version":"4.1.32"},"tags":[{"name":"Crypto","description":"Operações de criptografia e descriptografia de dados"}],"servers":[{"url":"https://apivin.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"DecryptDataInput":{"allOf":[{"$ref":"#/components/schemas/CryptoInputBase"},{"type":"object","required":["p_h_data"],"properties":{"p_h_data":{"type":"string","description":"Dados criptografados a serem descriptografados em formato Hex"}}}]},"CryptoInputBase":{"type":"object","required":["client_id","keyId","modeEncFlag","data_fmt"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave no banco de dados"},"modeEncFlag":{"type":"string","description":"Modo de operação da cifra:\n- `00`: ECB (padrão se null ou valor não listado)\n- `01`: CBC (requer IV)\n- `02`: CFB8 (requer IV)\n- `03`: CFB64 (requer IV)\n"},"ksn_desc":{"type":"string","nullable":true,"description":"Descritor KSN — necessário apenas se o keyId for do tipo BDK (DUKPT)"},"ksn":{"type":"string","nullable":true,"description":"KSN — necessário apenas se o keyId for do tipo BDK (DUKPT)"},"iv":{"type":"string","nullable":true,"description":"Vetor de inicialização em Hex — obrigatório nos modos 01, 02, 03"},"data_fmt":{"type":"string","enum":["H","T"],"description":"Formato dos dados de entrada:\n- `H`: Hexadecimal\n- `T`: Texto\n"}}},"ReturnMultiValue":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","description":"Valor de retorno simples (geralmente vazio em sucesso)"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com os valores de retorno da operação"},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retDesc":{"type":"string","description":"Descrição do resultado"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `-1`: Erro interno\n- `-2`: Formato inválido\n- `137`: Malformação da requisição\n- `155`: Chave não encontrada no banco de dados\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDesc":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldCrypto/DecryptData":{"post":{"tags":["Crypto"],"summary":"Descriptografar dados","description":"Retorna os dados descriptografados e o IV (se aplicável) em formato Hex.\nEm caso de erro, retorna os campos de erro (retCode e retDescription).\n\nRetorna em `retMultiValue`:\n- `retMultiValue[0]` = msgRespDecrypted → Mensagem descriptografada\n- `retMultiValue[1]` = ivResp → IV para a próxima chamada de criptografia,\n apenas nos modos modeEncFlag 01, 02, 03. Caso contrário, será null.\n\nO campo `data_fmt` aceita apenas `H` (Hexadecimal) ou `T` (Texto). O formato `B` não é suportado.\n","operationId":"decryptData","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecryptDataInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnMultiValue"}}}},"400":{"description":"Requisição inválida — formato de data_fmt incorreto ou campo obrigatório ausente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"404":{"description":"Chave não encontrada no banco de dados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
## The CryptoInputBase object
```json
{"openapi":"3.0.3","info":{"title":"PayShield Crypto API","version":"4.1.32"},"components":{"schemas":{"CryptoInputBase":{"type":"object","required":["client_id","keyId","modeEncFlag","data_fmt"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave no banco de dados"},"modeEncFlag":{"type":"string","description":"Modo de operação da cifra:\n- `00`: ECB (padrão se null ou valor não listado)\n- `01`: CBC (requer IV)\n- `02`: CFB8 (requer IV)\n- `03`: CFB64 (requer IV)\n"},"ksn_desc":{"type":"string","nullable":true,"description":"Descritor KSN — necessário apenas se o keyId for do tipo BDK (DUKPT)"},"ksn":{"type":"string","nullable":true,"description":"KSN — necessário apenas se o keyId for do tipo BDK (DUKPT)"},"iv":{"type":"string","nullable":true,"description":"Vetor de inicialização em Hex — obrigatório nos modos 01, 02, 03"},"data_fmt":{"type":"string","enum":["H","T"],"description":"Formato dos dados de entrada:\n- `H`: Hexadecimal\n- `T`: Texto\n"}}}}}}
```
## The EncryptDataInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield Crypto API","version":"4.1.32"},"components":{"schemas":{"EncryptDataInput":{"allOf":[{"$ref":"#/components/schemas/CryptoInputBase"},{"type":"object","required":["p_ht_data"],"properties":{"p_ht_data":{"type":"string","description":"Dados a serem criptografados em formato H (Hex) ou T (Texto)"},"b_data":{"type":"string","nullable":true,"description":"Dados em formato binário (uso reservado)"}}}]},"CryptoInputBase":{"type":"object","required":["client_id","keyId","modeEncFlag","data_fmt"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave no banco de dados"},"modeEncFlag":{"type":"string","description":"Modo de operação da cifra:\n- `00`: ECB (padrão se null ou valor não listado)\n- `01`: CBC (requer IV)\n- `02`: CFB8 (requer IV)\n- `03`: CFB64 (requer IV)\n"},"ksn_desc":{"type":"string","nullable":true,"description":"Descritor KSN — necessário apenas se o keyId for do tipo BDK (DUKPT)"},"ksn":{"type":"string","nullable":true,"description":"KSN — necessário apenas se o keyId for do tipo BDK (DUKPT)"},"iv":{"type":"string","nullable":true,"description":"Vetor de inicialização em Hex — obrigatório nos modos 01, 02, 03"},"data_fmt":{"type":"string","enum":["H","T"],"description":"Formato dos dados de entrada:\n- `H`: Hexadecimal\n- `T`: Texto\n"}}}}}}
```
## The DecryptDataInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield Crypto API","version":"4.1.32"},"components":{"schemas":{"DecryptDataInput":{"allOf":[{"$ref":"#/components/schemas/CryptoInputBase"},{"type":"object","required":["p_h_data"],"properties":{"p_h_data":{"type":"string","description":"Dados criptografados a serem descriptografados em formato Hex"}}}]},"CryptoInputBase":{"type":"object","required":["client_id","keyId","modeEncFlag","data_fmt"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave no banco de dados"},"modeEncFlag":{"type":"string","description":"Modo de operação da cifra:\n- `00`: ECB (padrão se null ou valor não listado)\n- `01`: CBC (requer IV)\n- `02`: CFB8 (requer IV)\n- `03`: CFB64 (requer IV)\n"},"ksn_desc":{"type":"string","nullable":true,"description":"Descritor KSN — necessário apenas se o keyId for do tipo BDK (DUKPT)"},"ksn":{"type":"string","nullable":true,"description":"KSN — necessário apenas se o keyId for do tipo BDK (DUKPT)"},"iv":{"type":"string","nullable":true,"description":"Vetor de inicialização em Hex — obrigatório nos modos 01, 02, 03"},"data_fmt":{"type":"string","enum":["H","T"],"description":"Formato dos dados de entrada:\n- `H`: Hexadecimal\n- `T`: Texto\n"}}}}}}
```
## The ReturnMultiValue object
```json
{"openapi":"3.0.3","info":{"title":"PayShield Crypto API","version":"4.1.32"},"components":{"schemas":{"ReturnMultiValue":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","description":"Valor de retorno simples (geralmente vazio em sucesso)"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com os valores de retorno da operação"},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retDesc":{"type":"string","description":"Descrição do resultado"}}}}}}
```
## The ReturnError object
```json
{"openapi":"3.0.3","info":{"title":"PayShield Crypto API","version":"4.1.32"},"components":{"schemas":{"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `-1`: Erro interno\n- `-2`: Formato inválido\n- `137`: Malformação da requisição\n- `155`: Chave não encontrada no banco de dados\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDesc":{"type":"string","description":"Descrição do erro"}}}}}}
```
# Integração Prática e Casos de Uso
Esta secção apresenta o roteiro recomendado para colocar o módulo Crypto em produção e detalha cenários reais de aplicação no ecossistema de pagamentos, ilustrando a sequência exata de chamadas de API .
### Fluxo de Integração Recomendado
As cinco etapas abaixo cobrem o ciclo de vida completo da integração da sua aplicação cliente ao módulo PayShield Crypto, desde o setup até à monitorização em produção .
#### 1. Provisionamento e Setup
* Solicite à equipa da **First Tech** a criação do seu `client_id` e o cadastro das chaves criptográficas necessárias .
* Armazene os `keyId` recebidos de forma segura nas configurações da sua aplicação.
* Defina, em conjunto com o seu time de segurança, os modos de operação (`modeEncFlag`) adequados para cada caso de uso.
#### 2. Gestão de Autenticação
* Obtenha o token Bearer junto ao serviço Auth0 da First Tech .
* Implemente cache do token: Respeite o *Time-To-Live* (TTL) fornecido.
* Renovação proativa: Implemente a renovação do token antes da sua expiração para evitar picos de erros `401` em transações críticas.
#### 3. Operação Padrão
* Construa o payload da requisição com atenção redobrada aos campos de dados (lembre-se: `p_ht_data` para cifragem/MAC e `p_h_data` para decifragem) .
* Configure *timeouts* HTTP adequados ao seu caso de uso (mais curtos para tráfego transacional online, mais longos para processamento *batch*).
* Analise sempre o `retCode` no envelope de resposta antes de validar a flag `retValid`.
#### 4. Tratamento de Erros e Resiliência
* Erros `4xx`: Geralmente indicam problemas estruturais na requisição (ex.: payload inválido, chave incorreta). Não aplique *retry* cego sem corrigir a origem do problema .
* Erros `5xx`: Podem representar falhas transitórias do serviço ou de rede. Implemente políticas de *retry* com *backoff* exponencial e *jitter* .
* Regra de Segurança: Registe nos *logs* os campos `retCode` e `retDesc`, mas nunca imprima o conteúdo em claro de `p_ht_data` ou os retornos criptografados.
#### 5. Observabilidade em Produção
* Métricas Mínimas: Monitorize a taxa de chamadas por endpoint, a latência nos percentis `p50`/`p95`/`p99`, e a volumetria de erros agrupada por `retCode` .
* Alertas: Configure alarmes para desvios de SLA (latência), incrementos súbitos do `retCode 155` (Chave não encontrada) ou respostas `401` persistentes.
### Casos de Uso Reais da Indústria
#### Cenário 1: Tokenização de PAN para Armazenamento
Desafio: Uma aplicação necessita de armazenar números de cartão (PAN) em base de dados própria, mantendo o dado cifrado em repouso e garantindo que as chaves não fiquem na posse da própria aplicação .
**Sequência de Operações:**
1. Ingestão: A aplicação recebe o PAN em claro via canal seguro (TLS) .
2. Cifragem: A API do cliente consome o endpoint `EncryptData` (modo CBC ou ECB) .
3. Retorno Seguro: O Hop devolve o PAN cifrado e o IV utilizado. Imediatamente, a API descarta o PAN em claro da memória .
4. Persistência: O PAN cifrado, o IV e o `keyId` são armazenados na base de dados .
5. Recuperação: Ao necessitar do dado (ex.: autorização), a base de dados fornece a cifra e o IV à API .
6. Decifragem: A API consome o endpoint `DecryptData` .
7. Entrega: O Hop devolve o PAN em claro, que é entregue à aplicação final e descartado da memória após o uso .
#### Cenário 2: Proteção de Campo Sensível em Mensagem ISO 8583
Desafio: Um *host* adquirente recebe mensagens transacionais (ISO 8583) de um POS contendo campos sensíveis cifrados com chave de sessão. O *host* precisa de os decifrar e re-cifrar com chave de zona antes de encaminhar à bandeira.
**Sequência de Operações:**
1. Origem: O POS envia a mensagem ISO 8583 com o campo sensível cifrado .
2. Decifragem Transitória: O *host* adquirente extrai o campo e consome o `DecryptData` no Hop (modo CBC) .
3. Tratamento: O Hop devolve o dado em claro. O *host* valida o conteúdo (ex.: formato, expiração do cartão) .
4. Re-cifragem (Roteamento): O *host* consome novamente o `EncryptData`, desta vez aplicando a chave ZPK específica para a bandeira ou emissor .
5. Finalização: A autorização retorna do emissor e é devolvida ao POS .
#### Cenário 3: Migração de Base com Rotação de Chaves
Desafio: Troca programada da chave criptográfica de uma base inteira de dados para cumprir exigências de conformidade (PCI DSS). A operação é feita em *batch* .
**Sequência de Operações:**
1. Leitura: O *Job* lê um lote de `N` registos cifrados e os seus respetivos IVs da base antiga .
2. Decifragem em Massa: O *Job* invoca o `SuperDecryptData` referenciando a chave antiga .
3. Memória Volátil: O Hop devolve a lista de dados em claro. Estes dados são mantidos apenas em memória e não são guardados em ficheiros intermediários .
4. Re-cifragem Individual: O *Job* itera sobre cada registo invocando `EncryptData` com o `keyId` da nova chave .
5. Recepção: O Hop devolve o novo conteúdo cifrado e o novo IV .
6. Persistência Atualizada: O *Job* grava o registo na base de dados utilizando o novo `keyId` e IV .
#### Cenário 4: MAC Multi-bloco em Comunicação Host-to-Host
Desafio: Envio de ficheiros de remessa ou mensagens muito longas entre dois *hosts* que precisam de ser autenticados com um único MAC, exigindo o particionamento do ficheiro em blocos suportáveis .
**Sequência de Operações:**
1. Primeiro Bloco: O *Host* de origem invoca `GenerateMac` com `macModeFlag = 1` no primeiro segmento .
2. IV Intermediário: O Hop devolve um IV parcial para encadeamento .
3. Blocos Intermediários: O *Host* itera sobre o ficheiro invocando `GenerateMac` com `macModeFlag = 2`, alimentando-o com o IV recebido na etapa anterior .
4. Bloco Final: O *Host* invoca `GenerateMac` com `macModeFlag = 3` com o segmento final. O Hop devolve o MAC definitivo .
5. Transmissão: A mensagem completa e o MAC são enviados ao destino .
6. Validação Rigorosa: O *Host* de destino reproduz o particionamento exato e invoca o `ValidateMac` (com flags 1, 2 e 3). O Hop devolve `retValid: true` se o ficheiro estiver intacto .
# Erros, Troubleshooting e Apêndices
Esta página consolida as diretrizes operacionais, o catálogo de resolução de falhas e o material de referência rápida para garantir uma integração segura, resiliente e de alta performance.
### Boas Práticas de Integração
#### Segurança
* Proteção de Logs: Nunca registe dados em claro (como o conteúdo não-cifrado de `p_ht_data`, PINs ou PANs) em *logs* da aplicação, ferramentas de APM (Application Performance Monitoring) ou consolas.
* Gestão do Vetor de Inicialização (IV): Utilize sempre IVs aleatórios e únicos por cada operação quando utilizar os modos encadeados (`01`, `02` ou `03`). Nunca reutilize um IV com a mesma chave.
* Preparação para Rotação de Chaves: Armazene sempre o `keyId`, os dados cifrados e o IV em conjunto na sua base de dados. Esta prática é essencial para suportar processos futuros de rotação de chave sem a necessidade de refazer a ingestão dos dados originais.
* Controlo de Acesso: Restrinja o acesso de rede ao endpoint `apivin.first-tech.net` através de uma *allowlist* de IPs, sempre que a arquitetura o permitir.
#### Performance
* Operações em Lote: Para cenários de alta volumetria, prefira utilizar o endpoint `SuperDecryptData` em vez de invocar o `DecryptData` individualmente para cada registo.
* Reutilização de Conexões: Reaproveite conexões HTTP (*keep-alive*). O serviço Hop V4 mantém uma conexão persistente e otimizada com o HSM.
* Gestão de Carga: Agende e distribua o processamento de *batch jobs* (lotes pesados) durante as janelas de menor movimento (*off-peak*), preservando assim a capacidade de processamento para as transações *online* de tempo real.
### Códigos de Erro e Troubleshooting
O envelope de erro segue a mesma estrutura do envelope de sucesso. O campo `retCode` indica o tipo específico da falha, enquanto o `retDesc` carrega a descrição textual do problema .
#### Status HTTP e a Taxonomia de `retCode`
Status HTTP
Significado Padrão
retCode
Descrição do Erro Interno
200
Operação realizada com sucesso .
0
Sucesso absoluto.
400
Requisição inválida (campo ausente ou formato incorreto) .
-2
Formato inválido (ex.: data_fmt fora do enum esperado).
400
-
137
Malformação da requisição (estrutura comprometida).
401
Não autorizado (Token Bearer ausente ou inválido) .
-
Ocorre verificação antes de atingir o HSM.
404
Chave não encontrada no banco de dados.
155
O keyId fornecido não existe ou não pertence ao seu cliente.
400, 404, 500
Erro interno do servidor ou falha genérica .
-1
Erro interno.
#### Guia de Resolução Rápida (Troubleshooting)
A tabela abaixo cruza os sintomas mais comuns com as suas prováveis causas e ações corretivas recomendadas:
Sintoma Observado
Causa Provável
Ação Corretiva
HTTP 401 em todas as chamadas
Token expirado ou ausente.
Renovar o token no Auth0; verificar se o cabeçalho Authorization está bem formatado.
retCode 155
O keyId não está cadastrado para o client_id informado.
Conferir o provisionamento da chave com a equipa da First Tech.
retCode 137 (com payload "aparentemente" correto)
Campo obrigatório ausente, formato inválido ou erro de digitação (ex.: enviar p_h_data quando o endpoint exige p_ht_data).
Validar de forma rigorosa o JSON contra o dicionário de dados da API.
retCode -2 no DecryptData
O campo data_fmt é incompatível com o conteúdo fornecido.
Garantir que o data_fmt é igual a "H" para todo e qualquer dado cifrado enviado para decifragem.
iv retornando null em retMultiValue[1]
O modo de operação selecionado não consome nem gera IV (ex.: ECB).
Trata-se do comportamento normal e esperado para o modo 00.
Latência alta em SuperDecryptData
Tamanho do lote excede a capacidade ideal por requisição.
Reduzir a quantidade de itens no arrayp_h_data.
MAC inválido (retValid: false) no ValidateMac
A sequência multi-bloco executada no Host de destino está incorreta.
Validar que os valores de macModeFlag, a ordem das chamadas e o repasse do IV intermediário replicam exatamente o que foi feito na geração do MAC.
HTTP 400 sem retCode útil
O conteúdo (body) da requisição está malformado a nível do próprio JSON.
Validar o JSON antes do envio (usar um linter ou esquema validador).
***
### Apêndice A. Glossário de Termos
Termo / Sigla
Definição
BDK
Base Derivation Key. Chave-mãe DUKPT a partir da qual as chaves de transação são derivadas.
CBC
Cipher Block Chaining. Modo de operação simétrico que encadeia os blocos via operação lógica XOR.
CFB
Cipher Feedback. Modo de operação que transforma uma cifra de bloco numa cifra de fluxo contínuo.
client_id
Identificador único do tenant (cliente) na plataforma Hop V4.
DUKPT
Derived Unique Key Per Transaction. Esquema criptográfico onde cada transação utiliza uma chave única que é derivada através do KSN.
ECB
Electronic Codebook. Modo de operação simétrico mais simples, que cifra cada bloco de forma independente.
HSM
Hardware Security Module. Dispositivo dedicado, de alta segurança, para a execução de operações criptográficas e gestão de chaves.
IV
Initialization Vector. Valor aleatório de partida utilizado nos modos encadeados (CBC, CFB).
JWT
JSON Web Token. Formato padrão do token de autenticação emitido pelo serviço Auth0.
keyId
Alias armazenado no banco de dados da plataforma que aponta para uma chave criptográfica física dentro do HSM.
KSN
Key Serial Number. Identificador necessário para realizar a derivação de chaves em transações DUKPT.
MAC
Message Authentication Code. Código gerado para garantir a integridade e a autenticidade de uma mensagem em trânsito.
p_ht_data
Campo do payload para enviar dados em formato Hexadecimal ou Texto (utilizado no Encrypt e MAC).
p_h_data
Campo do payload exclusivo para enviar dados em formato Hexadecimal (utilizado no Decrypt e SuperDecrypt).
PAN
Primary Account Number. Número principal impresso no cartão de pagamento.
TPK / ZPK
Terminal PIN Key e Zone PIN Key. Chaves que protegem o PIN entre o terminal/host e entre instituições, respetivamente.
### Apêndice B. Referência Rápida de Endpoints
Consulte esta tabela para mapear rapidamente a operação que deseja realizar com o seu respetivo *endpoint* e campo de dados principal.
Operação
Endpoint da API
Campo de Entrada
Suporta Lote (Batch)?
Cifrar
/v4/PayShieldCrypto/EncryptData
p_ht_data
Não.
Decifrar
/v4/PayShieldCrypto/DecryptData
p_h_data
Não.
Decifrar Lote
/v4/PayShieldCrypto/SuperDecryptData
p_h_data[]
Sim.
Gerar MAC
/v4/PayShieldCrypto/GenerateMac
p_ht_data
Multi-bloco (via macModeFlag).
Validar MAC
/v4/PayShieldCrypto/ValidateMac
p_ht_data
Multi-bloco (via macModeFlag).
# Introdução e Fundamentos
O módulo PayShield CVV da plataforma Hop V4 expõe operações via API REST para a geração e validação de códigos de verificação de cartão. Este módulo cobre tanto os códigos estáticos (CVV1, CVV2) gravados ou impressos no cartão, quanto os códigos dinâmicos (dCVV, CVC3) utilizados em transações modernas .
Esta documentação é a referência técnica oficial para equipas de desenvolvimento e integração que vão consumir estes endpoints em sistemas de emissão, autorização e validação de cartões.
#### Pré-requisitos de Integração
Antes de iniciar o consumo dos endpoints, certifique-se de que o seu ambiente cumpre as seguintes exigências:
* Credenciais OAuth2: Client ID e Client Secret válidos para o *tenant* Auth0 da First Tech, com permissão de acesso ao módulo PayShield CVV.
* Client ID do Tenant: O `client_id` numérico atribuído pela First Tech (este identificador é distinto do Client ID utilizado no Auth0).
* Chaves Criptográficas Provisionadas: As chaves precisam estar cadastradas previamente no banco do HSM através do módulo PayShield Key Manager. Serão necessárias chaves do tipo CVK para as operações estáticas e MKAC para as operações dinâmicas.
* Ambiente de Homologação: Acesso liberado ao ambiente de testes para validação da integração antes da passagem para produção.
### O que é CVV/CVC
O CVV (*Card Verification Value*), também conhecido como CVC (*Card Verification Code*) pela MasterCard, é um código numérico curto — tipicamente de três dígitos — utilizado para verificar a posse física do cartão e a integridade dos dados durante uma transação .
O código é gerado através de uma chave criptográfica do emissor (a CVK) combinada com os dados do próprio cartão (PAN, data de expiração e *service code*). Por depender dessa chave segura, apenas o emissor possui a capacidade de validá-lo de forma autêntica .
#### Os Três Tipos de CVV na Hop V4
A API determina o tipo de CVV a ser processado através do campo `serviceCode` enviado na requisição:
Tipo
serviceCode a enviar
Onde aparece
Característica
CVV1 (CVC1)
O valor real do track
Tarja magnética / chip
Estático, gravado digitalmente no cartão.
CVV2 (CVC2)
000
Verso do plástico
Estático, impresso fisicamente.
dCVV (CVC3)
999
Transações contactless / chip
Dinâmico, recalculado a cada transação.
#### CVV Estático vs. CVV Dinâmico
Compreender esta divisão dita qual endpoint deve utilizar:
* CVV Estático (CVV1 e CVV2): É gerado uma única vez no momento da emissão. Como o valor permanece inalterado até a substituição do cartão, é vulnerável se intercetado em fraudes *card-not-present* .
* Endpoints associados: `GenerateCV`, `SuperGenerateCV` e `ValidateCV`.
* CVV Dinâmico (dCVV/CVC3): O código é recalculado pelo cartão a cada nova transação (via chip ou aproximação) utilizando um contador interno (ATC) e dados da bandeira. Isso garante não apenas a posse do cartão, mas a unicidade daquela transação específica.
* Endpoint associado: `VerifyDynCV`.
### Arquitetura e Autenticação
#### Base URL
Todas as requisições para o módulo CVV devem ser direcionadas à seguinte URL base : `https://apivin.first-tech.net/v4/PayShieldCVV/`
#### Autenticação Bearer (JWT)
Todos os endpoints exigem autenticação por token Bearer JWT, que deve ser enviado no cabeçalho `Authorization` da requisição HTTP :
```http
HTTP
Authorization: Bearer
Content-Type: application/json
Accept: */*
```
#### Identificação do Cliente e Chave
* Campo `client_id`: Presente no corpo (*body*) de todas as requisições. É a identificação do cliente na plataforma First Tech. As chaves criptográficas utilizadas pertencem a este identificador.
* Campo `keyId`: É o *alias* da chave CVK ou MKAC no banco do HSM. O formato padrão segue a estrutura `client-{client_id}-XX-key-id-XXXX-CVK`
# Padrões de Resposta e Schemas
Os endpoints do módulo CVV partilham um conjunto de *schemas* (modelos de objetos) estruturados como heranças de uma base comum. Conhecer essa arquitetura facilita o reaproveitamento de DTOs (*Data Transfer Objects*) no código da sua aplicação .
### Padrões de Resposta (Envelopes)
Todas as respostas do módulo seguem um envelope unificado. A validação do sucesso de uma chamada deve sempre analisar primeiro o campo `retCode` (onde `0` significa sucesso e qualquer outro valor indica um código de erro proveniente do HSM).
#### ReturnSingle
Utilizado pelos endpoints `GenerateCV`, `ValidateCV` e `VerifyDynCV` (quando o retorno esperado é apenas um valor único).
Campo
Tipo
Descrição
retCode
integer
Código de retorno. 0 = sucesso; outros valores indicam erro.
retValue
string
Valor de retorno simples (o CVV gerado ou uma descrição como "CVV Validated").
retMultiValue
any
Sempre null nestes endpoints.
retValid
boolean
Indica se a operação global foi bem-sucedida.
retDesc
string
Descrição textual do resultado (ex.: "OK" ou "CVV failed verification").
#### ReturnMultiValue
Utilizado exclusivamente pelo endpoint `SuperGenerateCV` (quando o retorno é uma matriz de múltiplos valores).
Campo
Tipo
Descrição
retCode
integer
Código de retorno. 0 = sucesso.
retValue
string
Sempre null neste schema.
retMultiValue
string[]
Array de strings contendo os CVVs gerados, apresentados exatamente na mesma ordem do array enviado na requisição.
retValid
boolean
Indica se a operação foi bem-sucedida.
retDesc
string
Descrição textual do resultado.
#### ReturnError
Ocorre em respostas HTTP 400, 404 e 500. Mantém o mesmo formato do `ReturnSingle`, mas com `retValid` igual a `false`, `retCode` preenchido com o código de falha do HSM e `retDesc` detalhando o erro .
### Schemas de Entrada (Requisição)
#### CvvInputBase (Campos Comuns)
*Schema* base que é herdado pelas operações de geração e validação estática.
Campo
Tipo
Obrigatório
Descrição Técnica
client_id
integer
Sim
Identificador numérico do cliente.
keyId
string
Sim
Alias da chave CVK no banco.
pan
string
Sim
PAN do cartão (1 a 19 dígitos numéricos).
expDate
string
Sim
Data de expiração no formato YYMM ou MMYY.
serviceCode
string
Sim
Service code do cartão.
#### Extensões por Endpoint
`GenerateCvInput`: Idêntico ao `CvvInputBase`. Não exige campos adicionais.
`SuperGenerateCvInput`: Estende o `CvvInputBase`, mas substitui o campo de *string* `serviceCode` pelo *array* `serviceCodeArray`.
* `serviceCodeArray` (`string[]`): *Array* de *service codes*. Gera um CVV distinto por cada elemento.
`ValidateCvInput`: Estende o `CvvInputBase` adicionando o código que será submetido a validação.
* `cv` (`string`): O CVV/CVC a ser validado. Exige exatamente 3 dígitos numéricos (Regex: `^[0-9]+$`).
* `dynCv` (`string`): Usado apenas se o `serviceCode` for `"999"`.
`VerifyDynCvInput` (Validação Dinâmica): Este *schema* é completamente autónomo (não herda do base). Utiliza a chave `MKAC` e possui campos exclusivos para mapear a perspetiva dinâmica da bandeira e versão. Os campos detalhados estarão descritos na secção dedicada à validação dinâmica.
# Referência da API — CVV
Esta secção detalha os três endpoints responsáveis pelo ciclo de vida do CVV estático (o código impresso no plástico ou gravado na tarja magnética e no chip). Estas operações utilizam chaves do tipo CVK.
## Gerar CVV/CVC
> Gera o CVV/CVC (Card Verification Value/Code) para um cartão.\
> Retorna o valor gerado em \`retValue\`.\
> Em caso de erro, retorna os campos de erro (\`retCode\` e \`retDesc\`).
```json
{"openapi":"3.0.3","info":{"title":"PayShield CVV API","version":"4.1.32"},"tags":[{"name":"CVV","description":"Operações de geração e validação de CVV/CVC estático e dinâmico"}],"servers":[{"url":"https://apivin.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"GenerateCvInput":{"allOf":[{"$ref":"#/components/schemas/CvvInputBase"}]},"CvvInputBase":{"type":"object","required":["client_id","keyId","pan","expDate","serviceCode"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave CVK no banco de dados"},"pan":{"type":"string","minLength":1,"maxLength":19,"description":"PAN do cartão (até 19 dígitos)"},"expDate":{"type":"string","description":"Data de expiração do cartão (formato YYMM ou MMYY conforme configuração do HSM)"},"serviceCode":{"type":"string","description":"Service Code do cartão:\n- Valor do track → CVV tipo 1 (CVV1)\n- `000` → CVV tipo 2 (CVV2)\n- `999` → CVV dinâmico (dCVV)\n"}}},"ReturnSingle":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","nullable":true,"description":"Valor de retorno simples"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retDesc":{"type":"string","description":"Descrição do resultado"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `01`: Falha na verificação do CVV / criptograma\n- `05`: Scheme, Version ID ou Key Derivation Method não reconhecido\n- `06`: Valor YHHHHCC inválido\n- `10`: Erro de paridade na chave CVK A/B ou MK\n- `27`: CVK não é double length\n- `52`: Discretionary Data CVS inválido\n- `68`: Comando desabilitado\n- `E9`: Valor de máscara CVC3 inválido\n- `EA`: Modified PSN Flag inválido\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDesc":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldCVV/GenerateCV":{"post":{"tags":["CVV"],"summary":"Gerar CVV/CVC","description":"Gera o CVV/CVC (Card Verification Value/Code) para um cartão.\nRetorna o valor gerado em `retValue`.\nEm caso de erro, retorna os campos de erro (`retCode` e `retDesc`).\n","operationId":"generateCV","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateCvInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnSingle"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"404":{"description":"Chave não encontrada no banco de dados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
## Gerar múltiplos CVV/CVC
> Versão estendida do GenerateCV que aceita um array de service codes (\`serviceCodeArray\`)\
> e retorna um CVV/CVC gerado para cada service code em \`retMultiValue\`.\
> \
> Útil para gerar CVV1, CVV2 e iCVV de um mesmo cartão em uma única chamada.
```json
{"openapi":"3.0.3","info":{"title":"PayShield CVV API","version":"4.1.32"},"tags":[{"name":"CVV","description":"Operações de geração e validação de CVV/CVC estático e dinâmico"}],"servers":[{"url":"https://apivin.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"SuperGenerateCvInput":{"type":"object","required":["client_id","keyId","pan","expDate","serviceCodeArray"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave CVK no banco de dados"},"pan":{"type":"string","minLength":1,"maxLength":19,"description":"PAN do cartão (até 19 dígitos)"},"expDate":{"type":"string","description":"Data de expiração do cartão"},"serviceCodeArray":{"type":"array","items":{"type":"string"},"description":"Array de service codes para geração de múltiplos CVVs em uma única chamada.\nCada elemento gera um CVV correspondente em `retMultiValue`.\n"}}},"ReturnMultiValue":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","nullable":true},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Array com os CVVs gerados — um por service code enviado"},"retValid":{"type":"boolean"},"retDesc":{"type":"string"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `01`: Falha na verificação do CVV / criptograma\n- `05`: Scheme, Version ID ou Key Derivation Method não reconhecido\n- `06`: Valor YHHHHCC inválido\n- `10`: Erro de paridade na chave CVK A/B ou MK\n- `27`: CVK não é double length\n- `52`: Discretionary Data CVS inválido\n- `68`: Comando desabilitado\n- `E9`: Valor de máscara CVC3 inválido\n- `EA`: Modified PSN Flag inválido\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDesc":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldCVV/SuperGenerateCV":{"post":{"tags":["CVV"],"summary":"Gerar múltiplos CVV/CVC","description":"Versão estendida do GenerateCV que aceita um array de service codes (`serviceCodeArray`)\ne retorna um CVV/CVC gerado para cada service code em `retMultiValue`.\n\nÚtil para gerar CVV1, CVV2 e iCVV de um mesmo cartão em uma única chamada.\n","operationId":"superGenerateCV","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuperGenerateCvInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnMultiValue"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"404":{"description":"Chave não encontrada no banco de dados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
## Validar CVV/CVC
> Valida o CVV/CVC de um cartão.\
> Retorna \`true\` em \`retValid\` se o CVV for válido, \`false\` caso contrário.\
> \
> O campo \`serviceCode\` define o tipo de CVV:\
> \- Valor do track → CVV tipo 1 (CVV1)\
> \- \`000\` → CVV tipo 2 (CVV2)\
> \- \`999\` → CVV dinâmico (dCVV)\
> \
> Em caso de erro, retorna os campos de erro (\`retCode\` e \`retDesc\`).
```json
{"openapi":"3.0.3","info":{"title":"PayShield CVV API","version":"4.1.32"},"tags":[{"name":"CVV","description":"Operações de geração e validação de CVV/CVC estático e dinâmico"}],"servers":[{"url":"https://apivin.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"ValidateCvInput":{"allOf":[{"$ref":"#/components/schemas/CvvInputBase"},{"type":"object","required":["cv"],"properties":{"cv":{"type":"string","minLength":3,"maxLength":3,"pattern":"^[0-9]+$","description":"CVV/CVC a ser validado (exatamente 3 dígitos numéricos)"},"dynCv":{"type":"string","nullable":true,"description":"CVV dinâmico (usado apenas para serviceCode `999`)"}}}]},"CvvInputBase":{"type":"object","required":["client_id","keyId","pan","expDate","serviceCode"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave CVK no banco de dados"},"pan":{"type":"string","minLength":1,"maxLength":19,"description":"PAN do cartão (até 19 dígitos)"},"expDate":{"type":"string","description":"Data de expiração do cartão (formato YYMM ou MMYY conforme configuração do HSM)"},"serviceCode":{"type":"string","description":"Service Code do cartão:\n- Valor do track → CVV tipo 1 (CVV1)\n- `000` → CVV tipo 2 (CVV2)\n- `999` → CVV dinâmico (dCVV)\n"}}},"ReturnSingle":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","nullable":true,"description":"Valor de retorno simples"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retDesc":{"type":"string","description":"Descrição do resultado"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `01`: Falha na verificação do CVV / criptograma\n- `05`: Scheme, Version ID ou Key Derivation Method não reconhecido\n- `06`: Valor YHHHHCC inválido\n- `10`: Erro de paridade na chave CVK A/B ou MK\n- `27`: CVK não é double length\n- `52`: Discretionary Data CVS inválido\n- `68`: Comando desabilitado\n- `E9`: Valor de máscara CVC3 inválido\n- `EA`: Modified PSN Flag inválido\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDesc":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldCVV/ValidateCV":{"post":{"tags":["CVV"],"summary":"Validar CVV/CVC","description":"Valida o CVV/CVC de um cartão.\nRetorna `true` em `retValid` se o CVV for válido, `false` caso contrário.\n\nO campo `serviceCode` define o tipo de CVV:\n- Valor do track → CVV tipo 1 (CVV1)\n- `000` → CVV tipo 2 (CVV2)\n- `999` → CVV dinâmico (dCVV)\n\nEm caso de erro, retorna os campos de erro (`retCode` e `retDesc`).\n","operationId":"validateCV","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateCvInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnSingle"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"404":{"description":"Chave não encontrada no banco de dados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
## Verificar CVV/CVC dinâmico
> Verifica o CVV/CVC dinâmico (dCVV/CVC3) de um cartão para transações contactless e chip.\
> Suporta múltiplas bandeiras: Visa (DCVV), MasterCard (CVC3/PINCVC3), American Express (ExpressPay) e Discover (ZIP DCVV).\
> \
> Retorna \`true\` em \`retValid\` se o CVV dinâmico for válido.\
> Em caso de erro, retorna os campos de erro (\`retCode\` e \`retDesc\`).\
> \
> O comportamento varia conforme o campo \`brand\` e \`dynCvVers\`:\
> \- \*\*Visa\*\* (\`brand: "Visa"\`, \`dynCvVers: 0\`): requer \`expDate\`, \`serviceCode\`, \`atc\`, \`dynCv\`\
> \- \*\*MasterCard\*\* (\`brand: "MasterCard"\`): requer \`ivcvc3\` ou \`trackData\` dependendo da versão\
> \- \*\*American Express\*\* (\`brand: "American Express"\`, \`dynCvVers: 0\`): suporte básico\
> \- \*\*Discover\*\* (\`brand: "Discover"\`): suporte básico
```json
{"openapi":"3.0.3","info":{"title":"PayShield CVV API","version":"4.1.32"},"tags":[{"name":"CVV","description":"Operações de geração e validação de CVV/CVC estático e dinâmico"}],"servers":[{"url":"https://apivin.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"VerifyDynCvInput":{"type":"object","required":["client_id","keyId","dynCv","pan","expDate","serviceCode","brand","dynCvVers","kdm","atc"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave MKAC no banco de dados"},"dynCv":{"type":"string","description":"CVV/CVC dinâmico a ser verificado (3N para DCVV ou 5A para CVC3/PINCVC3)"},"pan":{"type":"string","description":"PAN do cartão"},"expDate":{"type":"string","description":"Data de expiração do cartão"},"serviceCode":{"type":"string","description":"Service Code do cartão"},"brand":{"type":"string","enum":["Visa","MasterCard","American Express","Discover"],"description":"Bandeira do cartão — determina o esquema de verificação utilizado"},"dynCvVers":{"type":"integer","description":"Versão do CVV dinâmico. Varia conforme a bandeira:\n- **Visa**: `0` (DCVV)\n- **MasterCard**: `0` (CVC3 com IVCVC3), `1` (CVC3 com PSN+IVCVC3), `2` (CVC3 com track data), `3` (PINCVC3)\n- **American Express**: `0` (ExpressPay 2.0)\n- **Discover**: `0` (ZIP DCVV), `1` (ZIP DCVV Plus)\n"},"kdm":{"type":"string","description":"Método de derivação de chave:\n- `A`: EMV 4.1 Book 2 Option A\n- `B`: EMV 4.1 Book 2 Option B\n- `2`: 16-byte AUKDCVV (apenas Discover)\n- `3`: 24-byte AUKDCVV (apenas Discover)\n"},"atc":{"type":"string","description":"Application Transaction Counter (6N para Visa, 5N para MasterCard)"},"psn":{"type":"string","nullable":true,"description":"PAN Sequence Number — obrigatório para MasterCard versões 1 e 2, e American Express"},"un":{"type":"string","nullable":true,"description":"Unpredictable Number — obrigatório para MasterCard"},"ivcvc3":{"type":"string","nullable":true,"description":"Issuer proprietary static data element — obrigatório para MasterCard versões 0 e 1"},"trackDataLen":{"type":"integer","nullable":true,"description":"Comprimento dos dados de track — obrigatório para MasterCard versões 2 e 3"},"trackData":{"type":"string","nullable":true,"description":"Dados estáticos do track 1 ou 2 — obrigatório para MasterCard versões 2 e 3"}}},"ReturnSingle":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","nullable":true,"description":"Valor de retorno simples"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retDesc":{"type":"string","description":"Descrição do resultado"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `01`: Falha na verificação do CVV / criptograma\n- `05`: Scheme, Version ID ou Key Derivation Method não reconhecido\n- `06`: Valor YHHHHCC inválido\n- `10`: Erro de paridade na chave CVK A/B ou MK\n- `27`: CVK não é double length\n- `52`: Discretionary Data CVS inválido\n- `68`: Comando desabilitado\n- `E9`: Valor de máscara CVC3 inválido\n- `EA`: Modified PSN Flag inválido\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDesc":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldCVV/VerifyDynCV":{"post":{"tags":["CVV"],"summary":"Verificar CVV/CVC dinâmico","description":"Verifica o CVV/CVC dinâmico (dCVV/CVC3) de um cartão para transações contactless e chip.\nSuporta múltiplas bandeiras: Visa (DCVV), MasterCard (CVC3/PINCVC3), American Express (ExpressPay) e Discover (ZIP DCVV).\n\nRetorna `true` em `retValid` se o CVV dinâmico for válido.\nEm caso de erro, retorna os campos de erro (`retCode` e `retDesc`).\n\nO comportamento varia conforme o campo `brand` e `dynCvVers`:\n- **Visa** (`brand: \"Visa\"`, `dynCvVers: 0`): requer `expDate`, `serviceCode`, `atc`, `dynCv`\n- **MasterCard** (`brand: \"MasterCard\"`): requer `ivcvc3` ou `trackData` dependendo da versão\n- **American Express** (`brand: \"American Express\"`, `dynCvVers: 0`): suporte básico\n- **Discover** (`brand: \"Discover\"`): suporte básico\n","operationId":"verifyDynCV","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyDynCvInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnSingle"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"404":{"description":"Chave não encontrada no banco de dados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
## The CvvInputBase object
```json
{"openapi":"3.0.3","info":{"title":"PayShield CVV API","version":"4.1.32"},"components":{"schemas":{"CvvInputBase":{"type":"object","required":["client_id","keyId","pan","expDate","serviceCode"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave CVK no banco de dados"},"pan":{"type":"string","minLength":1,"maxLength":19,"description":"PAN do cartão (até 19 dígitos)"},"expDate":{"type":"string","description":"Data de expiração do cartão (formato YYMM ou MMYY conforme configuração do HSM)"},"serviceCode":{"type":"string","description":"Service Code do cartão:\n- Valor do track → CVV tipo 1 (CVV1)\n- `000` → CVV tipo 2 (CVV2)\n- `999` → CVV dinâmico (dCVV)\n"}}}}}}
```
## The GenerateCvInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield CVV API","version":"4.1.32"},"components":{"schemas":{"GenerateCvInput":{"allOf":[{"$ref":"#/components/schemas/CvvInputBase"}]},"CvvInputBase":{"type":"object","required":["client_id","keyId","pan","expDate","serviceCode"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave CVK no banco de dados"},"pan":{"type":"string","minLength":1,"maxLength":19,"description":"PAN do cartão (até 19 dígitos)"},"expDate":{"type":"string","description":"Data de expiração do cartão (formato YYMM ou MMYY conforme configuração do HSM)"},"serviceCode":{"type":"string","description":"Service Code do cartão:\n- Valor do track → CVV tipo 1 (CVV1)\n- `000` → CVV tipo 2 (CVV2)\n- `999` → CVV dinâmico (dCVV)\n"}}}}}}
```
## The SuperGenerateCvInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield CVV API","version":"4.1.32"},"components":{"schemas":{"SuperGenerateCvInput":{"type":"object","required":["client_id","keyId","pan","expDate","serviceCodeArray"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave CVK no banco de dados"},"pan":{"type":"string","minLength":1,"maxLength":19,"description":"PAN do cartão (até 19 dígitos)"},"expDate":{"type":"string","description":"Data de expiração do cartão"},"serviceCodeArray":{"type":"array","items":{"type":"string"},"description":"Array de service codes para geração de múltiplos CVVs em uma única chamada.\nCada elemento gera um CVV correspondente em `retMultiValue`.\n"}}}}}}
```
## The ValidateCvInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield CVV API","version":"4.1.32"},"components":{"schemas":{"ValidateCvInput":{"allOf":[{"$ref":"#/components/schemas/CvvInputBase"},{"type":"object","required":["cv"],"properties":{"cv":{"type":"string","minLength":3,"maxLength":3,"pattern":"^[0-9]+$","description":"CVV/CVC a ser validado (exatamente 3 dígitos numéricos)"},"dynCv":{"type":"string","nullable":true,"description":"CVV dinâmico (usado apenas para serviceCode `999`)"}}}]},"CvvInputBase":{"type":"object","required":["client_id","keyId","pan","expDate","serviceCode"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave CVK no banco de dados"},"pan":{"type":"string","minLength":1,"maxLength":19,"description":"PAN do cartão (até 19 dígitos)"},"expDate":{"type":"string","description":"Data de expiração do cartão (formato YYMM ou MMYY conforme configuração do HSM)"},"serviceCode":{"type":"string","description":"Service Code do cartão:\n- Valor do track → CVV tipo 1 (CVV1)\n- `000` → CVV tipo 2 (CVV2)\n- `999` → CVV dinâmico (dCVV)\n"}}}}}}
```
## The ReturnSingle object
```json
{"openapi":"3.0.3","info":{"title":"PayShield CVV API","version":"4.1.32"},"components":{"schemas":{"ReturnSingle":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","nullable":true,"description":"Valor de retorno simples"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retDesc":{"type":"string","description":"Descrição do resultado"}}}}}}
```
## The ReturnMultiValue object
```json
{"openapi":"3.0.3","info":{"title":"PayShield CVV API","version":"4.1.32"},"components":{"schemas":{"ReturnMultiValue":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","nullable":true},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Array com os CVVs gerados — um por service code enviado"},"retValid":{"type":"boolean"},"retDesc":{"type":"string"}}}}}}
```
## The ReturnError object
```json
{"openapi":"3.0.3","info":{"title":"PayShield CVV API","version":"4.1.32"},"components":{"schemas":{"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `01`: Falha na verificação do CVV / criptograma\n- `05`: Scheme, Version ID ou Key Derivation Method não reconhecido\n- `06`: Valor YHHHHCC inválido\n- `10`: Erro de paridade na chave CVK A/B ou MK\n- `27`: CVK não é double length\n- `52`: Discretionary Data CVS inválido\n- `68`: Comando desabilitado\n- `E9`: Valor de máscara CVC3 inválido\n- `EA`: Modified PSN Flag inválido\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDesc":{"type":"string","description":"Descrição do erro"}}}}}}
```
# Integração e Exemplos Práticos
Esta secção detalha como os endpoints do módulo CVV se encaixam na arquitetura real de um emissor ou processador de cartões, apresentando os fluxos recomendados, boas práticas de segurança e exemplos de código prontos a utilizar.
### Fluxo Típico: Emissão de Cartão
No momento da personalização e emissão de um novo cartão, o emissor necessita tipicamente de gerar os três valores de CVV de uma só vez .
O fluxo recomendado é o seguinte:
1. Autenticação: Obter o token JWT via Auth0 (utilizando o *grant* `client_credentials`), que é válido tipicamente por 24 horas.
2. Geração em Lote: Invocar o endpoint `SuperGenerateCV` enviando o *array* `["