> 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-cvv/introducao-e-fundamentos.md).

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

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Tipo</th><th>serviceCode a enviar</th><th>Onde aparece</th><th>Característica</th></tr></thead><tbody><tr><td>CVV1 (CVC1)</td><td><em>O valor real do track</em></td><td>Tarja magnética / chip</td><td>Estático, gravado digitalmente no cartão.</td></tr><tr><td>CVV2 (CVC2)</td><td><code>000</code></td><td>Verso do plástico</td><td>Estático, impresso fisicamente.</td></tr><tr><td>dCVV (CVC3)</td><td><code>999</code></td><td>Transações <em>contactless</em> / chip</td><td>Dinâmico, recalculado a cada transação.</td></tr></tbody></table>

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


---

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