> For the complete documentation index, see [llms.txt](https://ftcoders.first-tech.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ftcoders.first-tech.com/landing-page/bem-vindo-hop-api-v4.md).

# 👋 Bem-vindo - HoP API v4

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:

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="image"></th></tr></thead><tbody><tr><td><h4>Visão de Produto</h4></td><td>O que é o Hop V4</td><td></td></tr><tr><td><h4>V3 → V4</h4></td><td>O que muda na migração</td><td></td></tr><tr><td><h4>Documentação</h4></td><td>Mapa da Documentação</td><td></td></tr><tr><td><h4>FAQ</h4></td><td>Sobre o Hop V4</td><td></td></tr><tr><td><h4>Suporte e Contatos</h4></td><td>Fale conosco</td><td></td></tr></tbody></table>

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

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Plano</th><th>Para quem</th><th>Faixa</th></tr></thead><tbody><tr><td>Start</td><td>Times técnicos avaliando a plataforma; fintechs em estágio inicial.</td><td>Ambientes de desenvolvimento, POCs e operações de baixo volume.</td></tr><tr><td>Fintech</td><td>Fintechs em produção, sub-adquirentes e processadoras em crescimento.</td><td>Volume médio, exigências de SLA produtivo.</td></tr><tr><td>Enterprise</td><td>Adquirentes, bandeiras e operações com necessidades específicas de SLA, customização e integração dedicada.</td><td>Alto volume, ambientes mission-critical, atendimento dedicado.</td></tr></tbody></table>

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

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Cripto-agilidade</th><th>Mais Performance</th><th>Mais Segurança</th></tr></thead><tbody><tr><td>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 </td><td><p>10 vezes mais Rápidos.</p><p>A nova versão mantém o mesmo consumo de recursos entregando 10 vezes mais performance paralela. Isso é mais robustez para você. </p></td><td><p>Entropia quântica</p><p>Chaves geradas a partir de aleatoriedade de origem quântica certificada, eliminando a previsibilidade de PRNGs tradicionais.</p></td></tr></tbody></table>

Para mais detalhes da migração verificar Manifesto\_Migracao\_Hop\_V4

### &#x20;Documentação

#### Materiais de apoio

Para entender o produto, suporte com a migração de versão, release notes:

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Documento</th><th>O que é</th><th>Quando ler</th><th>Para quem</th></tr></thead><tbody><tr><td>Autenticação (OAuth2)</td><td>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</td><td>Antes da primeira chamada à API. Releitura ao implementar rotação de credenciais ou ao intefgrar novo ambiente.</td><td>Time técnico, desenvolvedores responsáveis pela integração</td></tr><tr><td>Tratamento de Erros</td><td>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</td><td>Durante o desenvolvimento, ao implementar lógica de retry/fallback e em troubleshooting de produção.</td><td>Desenvolvedores, time de operações/SRE e suporte técnico.</td></tr><tr><td>Release Notes HoP API V4</td><td>Histórico cronológico de versões do HoP V4: Novas funcionalidades, correções, breaking changes e depreciações por versão.</td><td>Ao subir de versão, antes de planejar atualização de integração e períodicamente para acompanhar a evolução do produto.</td><td>Time técnico, arquitetos, time de produtos.</td></tr><tr><td>Manifesto de Migração V3 → V4</td><td>Documento detalhado com as 5 etapas da migração, prazos, responsáveis e checklists.</td><td>No kickoff da migração e durante toda a execução.</td><td>Cliente migrando da V3, time técnico do cliente, Onboarding.</td></tr></tbody></table>

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

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Módulo</th><th>Endpoints principais</th><th>Status</th></tr></thead><tbody><tr><td>Key Manager</td><td>Geração e importação de chaves (ZMK, ZPK, CVK, DEK, ZEK, BDK, ZAK, KERG).</td><td>✅ Disponível</td></tr><tr><td>Crypto</td><td>EncryptData, DecryptData, SuperDecryptData, GenerateMac, ValidateMac.</td><td>✅ Disponível</td></tr><tr><td>PIN</td><td>Geração, tradução e validação de blocos de PIN.</td><td>✅ Disponível</td></tr><tr><td>CVV</td><td>Generate, Super Generate, Validate.</td><td>✅ Disponível</td></tr><tr><td>PAN</td><td>Encriptação e manipulação de PAN.</td><td>✅ Disponível</td></tr><tr><td>EMV</td><td>ARQC, ARPC, derivação de chaves de sessão.</td><td>✅ Disponível</td></tr><tr><td>RSA</td><td>Import/Export PKCS#1 v1.5, OAEP SHA-1 a SHA-512.</td><td>✅ Disponível</td></tr></tbody></table>

{% 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 %}


---

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

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

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

```
GET https://ftcoders.first-tech.com/landing-page/bem-vindo-hop-api-v4.md?ask=<question>&goal=<endgoal>
```

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

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

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