Integração, Boas Práticas e Apêndices

Fluxo de Integração Recomendado

As cinco etapas abaixo cobrem a integração ponta-a-ponta de uma aplicação cliente ao módulo PayShield Pan .

Provisionamento

• Solicite à First Tech a criação do client_id e o registo das chaves criptográficas necessárias (LMK do tenant e as ZPKs por canal: emissor, adquirente, terminais, gráfica) .

• Mapeie cada caso de uso a um par origem/destino e ao endpoint correspondente, conforme a matriz de operações (Secção 3).

• Documente internamente os keyIds e os seus algoritmos (AES vs 3DES), uma vez que o algoritmo não é exposto pela API e tem de ser conhecido pelo integrador.

Autenticação

• Obtenha o token Bearer junto ao Auth0 da First Tech .

• Implemente um sistema de cache do token, respeitando o TTL (Time-To-Live) fornecido pelo provedor.

• Implemente a renovação proativa antes da expiração para evitar erros 401 em transações críticas.

Operação

• Construa o body de acordo com o endpoint alvo. Tenha especial atenção às convenções de nome de campo (ex.: zpkKeyIdSrc/Dst em PinEmbossing/PinInternalization, versus keyId em TranslatePin*) .

• Valide a compatibilidade formato × algoritmo antes de enviar (Secção 4.3).

• Trate a resposta inspecionando primeiro o retCode antes de avaliar a flag retValid.

Tratamento de Erros

• O retCode 01 no ValidatePinIssuerKey é a resposta esperada quando o PIN está incorreto; não se trata de um erro técnico .

• Os retCode 10 ou 11 (paridade de chave) indicam que a chave está corrompida e precisa de ser reprovisionada (abra um chamado com a First Tech).

• O retCode 17 indica que a tradução para o par origem/destino está bloqueada pelas políticas do HSM.

• O retCode 69 (formato desabilitado) indica uma violação da matriz de compatibilidade (ex.: formato 48 em 3DES).

• Os erros 5xx podem ser transitórios. Implemente um mecanismo de retry com backoff exponencial e jitter, mas NUNCA registe o PIN nos logs durante este processo.

Observabilidade

• Métricas Mínimas: Monitorize a taxa de chamadas por endpoint, a latência nos percentis p50/p95/p99, e a taxa de erro agrupada por retCode .

• Alertas: Configure alarmes em caso de desvio de SLA, num incremento súbito de retCode 01 (que pode indicar um ataque de força bruta), em erros 401 persistentes, e em quaisquer retCodes de paridade.

• Regra de Ouro (Logs): É estritamente PROIBIDO registar em log os campos pin, pinDb, pinBlockSrc, generatedPin ou qualquer conteúdo do retMultiValue. Registe apenas o client_id, o endpoint, o retCode e a duração da chamada.

---

Boas Práticas

Segurança

• O PIN em claro NUNCA deve ser visto pela aplicação. Toda a manipulação acontece sob cifragem (LMK, ZPK, TPK). Se o desenho arquitetural exigir o PIN em claro, o desenho está incorreto .

• Restrinja o acesso ao endpoint apivin.first-tech.net através de uma allowlist de IPs, sempre que possível.

• Implemente rate limits por client_id na sua infraestrutura para evitar enumeração de PINs (ex.: um máximo de N tentativas por PAN por hora).

• Em fluxos de ValidatePinIssuerKey, propague apenas o valor booleano do retValid para a camada de negócio; nunca exponha o retDescription ao cliente final.

Performance

• Reaproveite as conexões HTTP (keep-alive). O serviço Hop V4 já mantém uma conexão persistente e otimizada com o HSM .

• Em jobs de migração, dimensione lotes pequenos (50 a 200 registos) para não saturar a fila de processamento do HSM.

• Distribua os jobs de migração durante as janelas de menor movimento (off-peak) para preservar a capacidade de processamento das transações online.

Guia de Troubleshooting Rápido

Sintoma Observado	Causa Provável	Ação Corretiva
HTTP 401 em todas as chamadas	Token expirado ou ausente.	Renovar token no Auth0; verificar header Authorization.
retCode 17 em PinEmbossing	Tradução LMK → ZPK desabilitada para o par de chaves.	Verificar as políticas do HSM aplicadas ao seu tenant.
retCode 69 em PinEmbossing com formato 48	Formato 48 não suportado em ZPK 3DES (destino).	Usar formatos 01-47 no pinBlockFmtDst.
retCode 81 com pinLength informado	Tamanho real do PIN no PinBlock difere do declarado.	Validar a rotina de geração do PinBlock na origem.
retCode 88	PinBlock com PIN de tamanho zero (alerta).	Revisar processo de geração na origem.
retCode 10 ou 11	Erro de paridade na chave.	Solicitar reprovisionamento da chave à First Tech.
ValidatePinIssuerKey sempre retorna retValid false	formatCode / formatCodeDb invertidos ou keyIds trocados.	Validar o payload rigorosamente contra o exemplo da Secção 15.3.
TranslatePan retorna formato inesperado	AES Key Block LMK força nativamente o formato 48 no resultado.	Documentar esta regra nas integrações downstream que processam a resposta.

---

Apêndices

Apêndice A - Glossário

AES	Advanced Encryption Standard. Algoritmo simétrico padrão (128, 192 e 256 bits).
AES Key Block LMK	Modelo de armazenamento de chaves AES no HSM em formato Key Block (TR-31).
3DES Key Block LMK	Modelo de armazenamento de chaves 3DES no HSM em formato Key Block.
BDK	Base Derivation Key. Chave-mãe DUKPT.
DUKPT	Derived Unique Key Per Transaction. Esquema de derivação por transação.
formatCode	Índice abreviado de formato de PinBlock (0/1/3/4).
ISO PIN Block Format 4	Formato moderno de PinBlock (Thales 48), exclusivo para chaves AES.
LMK	Local Master Key. Chave-mestra AES interna do HSM da First Tech.
pinBlockFmt	Código direto Thales de formato de PinBlock (01, 02... 48).
TPK / ZPK	Terminal PIN Key / Zone PIN Key. Chaves partilhadas entre zonas ou terminais.
Variant LMK	Modelo legado de armazenamento de chaves no HSM (anterior ao Key Block).

Apêndice B - Referência Rápida de Endpoints

Gerar PIN sob LMK	/v4/PayShieldPan/GeneratePin	LMK
Gerar PIN sob ZPK do emissor	/v4/PayShieldPan/GeneratePinIssuerKey	ZPK
LMK AES → ZPK 3DES	/v4/PayShieldPan/PinEmbossing	AES → 3DES
ZPK 3DES → LMK AES	/v4/PayShieldPan/PinInternalization	3DES → AES
LMK AES → ZPK AES	/v4/PayShieldPan/TranslatePinLmkToZpk	AES → AES
ZPK AES → LMK AES	/v4/PayShieldPan/TranslatePinZpkToLmk	AES → AES
Trocar PAN preservando PIN	/v4/PayShieldPan/TranslatePan	LMK → LMK
Trocar PAN + traduzir PIN	/v4/PayShieldPan/TranslatePinPan	LMK → ZPK
Validar PIN recebido	/v4/PayShieldPan/ValidatePinIssuerKey	ZPK 3DES → LMK AES (validação)