👋 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 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:
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.
Alto volume, ambientes mission-critical, atendimento dedicado.
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.
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:
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.
Key Manager
Geração e importação de chaves (ZMK, ZPK, CVK, DEK, ZEK, BDK, ZAK, KERG).
✅ Disponível
Crypto
EncryptData, DecryptData, SuperDecryptData, GenerateMac, ValidateMac.
✅ Disponível
PIN
Geração, tradução e validação de blocos de PIN.
✅ Disponível
CVV
Generate, Super Generate, Validate.
✅ Disponível
PAN
Encriptação e manipulação de PAN.
✅ Disponível
EMV
ARQC, ARPC, derivação de chaves de sessão.
✅ Disponível
RSA
Import/Export PKCS#1 v1.5, OAEP SHA-1 a SHA-512.
✅ Disponível
💡 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.
Last updated