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
Authorization: Bearer <TOKEN_JWT>
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