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

# Introdução e Fundamentos

### Introdução

O módulo PayShield Pan da plataforma Hop V4 constitui o núcleo de gestão criptográfica de PIN e PAN da First Tech. A API expõe operações para geração, tradução entre chaves de diferentes algoritmos (3DES e AES) e domínios (LMK e ZPK), além da validação e re-cifragem de PIN sob mudança de PAN.

Embora o módulo se denomine "Pan", a maioria dos seus *endpoints* opera sobre o PIN — sendo que apenas o `TranslatePan` e o `TranslatePinPan` envolvem a alteração efetiva do PAN. Este documento serve como referência técnica completa, detalhando os modelos de dados, a taxonomia de erros e os fluxos de integração para o ciclo de vida do PIN.

#### Público-alvo

* Desenvolvedores encarregues da integração de aplicações ou *hosts* ao Hop V4 para operações de PIN e PAN.
* Arquitetos de sistemas para avaliação de criptografia como serviço.
* Equipas de segurança da informação e de operações responsáveis pela migração e ciclo de vida de cartões.

#### Pré-requisitos

* Cliente devidamente provisionado na plataforma Hop V4 com `client_id` atribuído.
* Chaves criptográficas (LMK, ZPK do emissor e ZPK do adquirente) cadastradas e associadas ao `client_id`.
* Credenciais Auth0 (token JWT) válidas e conectividade autorizada para o *endpoint* `apivin.first-tech.net`.

***

### Fundamentos

#### Conceitos-chave

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Termo</th><th>Significado</th></tr></thead><tbody><tr><td>LMK</td><td><em>Local Master Key</em>. Chave-mestra do HSM da First Tech, utilizada para proteger PINs em repouso e como ponto de entrada/saída para traduções. Tipicamente AES.</td></tr><tr><td>ZPK</td><td><em>Zone PIN Key</em>. Chave partilhada entre instituições (zona de confiança) entre adquirente, emissor, bandeira ou gráfica. Pode ser 3DES ou AES.</td></tr><tr><td>TPK</td><td><em>Terminal PIN Key</em>. Chave que protege o PIN entre o terminal (POS, ATM) e o adquirente. Tratada como uma ZPK específica de canal.</td></tr><tr><td>PinBlock</td><td>Bloco padronizado que encapsula o PIN para transmissão segura. Suporta múltiplos formatos ISO e proprietários.</td></tr><tr><td>Embossing</td><td>Refere-se à tradução de LMK para ZPK destinada a um canal externo (gráfica, terminal).</td></tr><tr><td>Internalization</td><td>Tradução inversa: traz o PIN de uma ZPK externa para a LMK interna do emissor.</td></tr></tbody></table>

#### Princípio Operacional

Toda a operação de PIN no Hop V4 referencia as chaves através do seu *alias* (`keyId`), garantindo que o material criptográfico real nunca saia do HSM. Da mesma forma, os PINs em claro nunca trafegam pela rede; estão sempre encapsulados num PinBlock cifrado.

O HoP atua como um tradutor entre domínios: recebe um PinBlock cifrado por uma chave de origem, realiza a decifragem e a re-cifragem com a chave de destino dentro do ambiente seguro, e devolve o novo PinBlock ao solicitante.

***

### Matriz de Operações

O módulo PAN suporta as traduções entre os domínios LMK e ZPK utilizando algoritmos AES e 3DES.

#### Tradução de PIN

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Origem</th><th>Destino</th><th>Algoritmos</th><th>Endpoint</th></tr></thead><tbody><tr><td>LMK</td><td>ZPK</td><td>AES → 3DES</td><td><code>PinEmbossing</code></td></tr><tr><td>LMK</td><td>ZPK</td><td>AES → AES</td><td><code>TranslatePinLmkToZpk</code></td></tr><tr><td>ZPK</td><td>LMK</td><td>3DES → AES</td><td><code>PinInternalization</code></td></tr><tr><td>ZPK</td><td>LMK</td><td>AES → AES</td><td><code>TranslatePinZpkToLmk</code></td></tr></tbody></table>

#### Geração, Tradução de PAN e Validação

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Operação</th><th>Endpoint</th><th>Observação</th></tr></thead><tbody><tr><td>Gerar PIN sob LMK</td><td><code>GeneratePin</code></td><td>Destinado a uso interno.</td></tr><tr><td>Gerar PIN sob ZPK</td><td><code>GeneratePinIssuerKey</code></td><td>Para envio à gráfica ou personalização.</td></tr><tr><td>Trocar PAN (Preservar PIN)</td><td><code>TranslatePan</code></td><td>Re-cifra o PIN para o novo PAN (reemissão).</td></tr><tr><td>Trocar PAN + Traduzir PIN</td><td><code>TranslatePinPan</code></td><td>Combina a troca de PAN com a tradução de chave.</td></tr><tr><td>Validar PIN</td><td><code>ValidatePinIssuerKey</code></td><td>Traduz e valida o PIN para autorização.</td></tr></tbody></table>

#### Flowchart de Decisão

O diagrama seguinte auxilia na escolha do *endpoint* adequado com base na operação e nas chaves envolvidas:

***

### Formatos de PinBlock

A API utiliza duas convenções para identificar o formato do PinBlock, dependendo do *endpoint* acionado.

#### Códigos Thales (`pinBlockFmt`)

Utilizada nos *endpoints* `PinEmbossing` e `PinInternalization`.

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Código</th><th>Padrão</th><th>Notas</th></tr></thead><tbody><tr><td>01</td><td>ISO 9564-1 Format 0</td><td>Formato mais comum em transações ISO 8583.</td></tr><tr><td>02</td><td>ISO 9564-1 Format 1</td><td>Sem PAN no bloco.</td></tr><tr><td>03/04/05</td><td>ISO Format 2 / Proprietário</td><td>Formatos para cartões com chip ou variantes Thales.</td></tr><tr><td>47/48</td><td>ISO 9564-1 Format 4</td><td>O Formato 48 é exclusivo para algoritmos AES.</td></tr></tbody></table>

#### Índices Abreviados (`formatCode`)

Utilizada nos *endpoints* `TranslatePinLmkToZpk`, `TranslatePinZpkToLmk`, `TranslatePan` e `TranslatePinPan`.

<table data-header-hidden="false" data-header-sticky><thead><tr><th>formatCode</th><th>Código Thales</th><th>Padrão Equivalente</th></tr></thead><tbody><tr><td>0</td><td>01</td><td>ISO 9564-1 Format 0.</td></tr><tr><td>1</td><td>05</td><td>Proprietário Thales.</td></tr><tr><td>3</td><td>47</td><td>ISO 9564-1 Format 4 (variante).</td></tr><tr><td>4</td><td>48</td><td>ISO 9564-1 Format 4 (padrão default).</td></tr></tbody></table>

#### Matriz de Compatibilidade

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Formato</th><th>Suporte AES</th><th>Suporte 3DES</th></tr></thead><tbody><tr><td>01-47</td><td>Sim</td><td>Sim</td></tr><tr><td>48</td><td>Sim</td><td>Não</td></tr></tbody></table>

O Formato 48 (ISO Format 4) requer obrigatoriamente chaves AES. Consequentemente, não é suportado como destino em operações que envolvam chaves 3DES, como no caso do `PinEmbossing`.

***

### Modelo de Retorno

| `retCode`        | `integer` | `0` indica sucesso; outros valores indicam erro. |
| ---------------- | --------- | ------------------------------------------------ |
| `retValue`       | `string`  | Texto informativo (ex.: `"PIN Generated"`).      |
| `retMultiValue`  | `any`     | Resultado estruturado (ex.: o PinBlock gerado).  |
| `retValid`       | `boolean` | Sucesso da operação ou validade do PIN.          |
| `retDescription` | `string`  | Descrição textual do resultado.                  |


---

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

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

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

```
GET https://ftcoders.first-tech.com/landing-page/modulo-pan/introducao-e-fundamentos.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.