> 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/hop-api/docs/cvv.md).
# CVV
## CVV Generate CV Module
> Returns the CV (Card Validation Value / Code) in (retValue).
```json
{"openapi":"3.0.3","info":{"title":"PayShield CVV API","version":"4.1.32"},"tags":[{"name":"CVV","description":"Operações de geração e validação de CVV/CVC estático e dinâmico"}],"servers":[{"url":"https://api-hext.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"GenerateCvInput":{"allOf":[{"$ref":"#/components/schemas/CvvInputBase"}]},"CvvInputBase":{"type":"object","required":["client_id","keyId","pan","expDate","serviceCode"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave CVK no banco de dados"},"pan":{"type":"string","minLength":1,"maxLength":19,"description":"PAN do cartão (até 19 dígitos)"},"expDate":{"type":"string","description":"Data de expiração do cartão (formato YYMM ou MMYY conforme configuração do HSM)"},"serviceCode":{"type":"string","description":"Service Code do cartão:\n- Valor do track → CVV tipo 1 (CVV1)\n- `000` → CVV tipo 2 (CVV2)\n- `999` → CVV dinâmico (dCVV)\n"}}},"ReturnSingle":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","nullable":true,"description":"Valor de retorno simples"},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retDescription":{"type":"string","description":"Descrição do resultado"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `500`: Erro interno\n- `400`: Requisição inválida\n- `155`: Chave não encontrada no banco de dados\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDescription":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldCVV/GenerateCV":{"post":{"tags":["CVV"],"summary":"CVV Generate CV Module","description":"Returns the CV (Card Validation Value / Code) in (retValue).\n","operationId":"generateCV","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateCvInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnSingle"}}}},"400":{"description":"Requisição inválida — campo obrigatório ausente ou formato incorreto","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"404":{"description":"Chave não encontrada no banco de dados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
## CVV Generate CV Module
> Returns the CVs (Card Validation Value / Code) in (retMultiValue).
```json
{"openapi":"3.0.3","info":{"title":"PayShield CVV API","version":"4.1.32"},"tags":[{"name":"CVV","description":"Operações de geração e validação de CVV/CVC estático e dinâmico"}],"servers":[{"url":"https://api-hext.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"SuperGenerateCvInput":{"type":"object","required":["client_id","keyId","pan","expDate","serviceCodeArray"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave CVK no banco de dados"},"pan":{"type":"string","minLength":1,"maxLength":19,"description":"PAN do cartão (até 19 dígitos)"},"expDate":{"type":"string","description":"Data de expiração do cartão"},"serviceCodeArray":{"type":"array","items":{"type":"string"},"description":"Array de service codes para geração de múltiplos CVVs em uma única chamada.\nCada elemento gera um CVV correspondente em `retMultiValue`.\n"}}},"ReturnMultiValue":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","nullable":true},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Array com os CVVs gerados — um por service code enviado"},"retValid":{"type":"boolean"},"retDescription":{"type":"string"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `500`: Erro interno\n- `400`: Requisição inválida\n- `155`: Chave não encontrada no banco de dados\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDescription":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldCVV/SuperGenerateCV":{"post":{"tags":["CVV"],"summary":"CVV Generate CV Module","description":"Returns the CVs (Card Validation Value / Code) in (retMultiValue).\n","operationId":"superGenerateCV","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuperGenerateCvInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnMultiValue"}}}},"400":{"description":"Requisição inválida — campo obrigatório ausente ou formato incorreto","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"404":{"description":"Chave não encontrada no banco de dados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
## CVV Dynamic Module
> Returns OK(true) or Not-Ok(false) in (retValid), in case of error, it returns details in the Error fields (retCode and RetDescription).
```json
{"openapi":"3.0.3","info":{"title":"PayShield CVV API","version":"4.1.32"},"tags":[{"name":"CVV","description":"Operações de geração e validação de CVV/CVC estático e dinâmico"}],"servers":[{"url":"https://api-hext.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"ValidateCvInput":{"allOf":[{"$ref":"#/components/schemas/CvvInputBase"},{"type":"object","required":["cv"],"properties":{"cv":{"type":"string","minLength":3,"maxLength":3,"pattern":"^[0-9]+$","description":"CVV/CVC a ser validado (exatamente 3 dígitos numéricos)"},"dynCv":{"type":"string","nullable":true,"description":"CVV dinâmico (usado apenas para serviceCode `999`)"}}}]},"CvvInputBase":{"type":"object","required":["client_id","keyId","pan","expDate","serviceCode"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave CVK no banco de dados"},"pan":{"type":"string","minLength":1,"maxLength":19,"description":"PAN do cartão (até 19 dígitos)"},"expDate":{"type":"string","description":"Data de expiração do cartão (formato YYMM ou MMYY conforme configuração do HSM)"},"serviceCode":{"type":"string","description":"Service Code do cartão:\n- Valor do track → CVV tipo 1 (CVV1)\n- `000` → CVV tipo 2 (CVV2)\n- `999` → CVV dinâmico (dCVV)\n"}}},"ReturnSingle":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","nullable":true,"description":"Valor de retorno simples"},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retDescription":{"type":"string","description":"Descrição do resultado"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `500`: Erro interno\n- `400`: Requisição inválida\n- `155`: Chave não encontrada no banco de dados\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDescription":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldCVV/ValidateCV":{"post":{"tags":["CVV"],"summary":"CVV Dynamic Module","description":"Returns OK(true) or Not-Ok(false) in (retValid), in case of error, it returns details in the Error fields (retCode and RetDescription).\n","operationId":"validateCV","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateCvInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnSingle"}}}},"400":{"description":"Requisição inválida — campo obrigatório ausente ou formato incorreto","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"404":{"description":"Chave não encontrada no banco de dados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
## The CvvInputBase object
```json
{"openapi":"3.0.3","info":{"title":"PayShield CVV API","version":"4.1.32"},"components":{"schemas":{"CvvInputBase":{"type":"object","required":["client_id","keyId","pan","expDate","serviceCode"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave CVK no banco de dados"},"pan":{"type":"string","minLength":1,"maxLength":19,"description":"PAN do cartão (até 19 dígitos)"},"expDate":{"type":"string","description":"Data de expiração do cartão (formato YYMM ou MMYY conforme configuração do HSM)"},"serviceCode":{"type":"string","description":"Service Code do cartão:\n- Valor do track → CVV tipo 1 (CVV1)\n- `000` → CVV tipo 2 (CVV2)\n- `999` → CVV dinâmico (dCVV)\n"}}}}}}
```
## The GenerateCvInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield CVV API","version":"4.1.32"},"components":{"schemas":{"GenerateCvInput":{"allOf":[{"$ref":"#/components/schemas/CvvInputBase"}]},"CvvInputBase":{"type":"object","required":["client_id","keyId","pan","expDate","serviceCode"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave CVK no banco de dados"},"pan":{"type":"string","minLength":1,"maxLength":19,"description":"PAN do cartão (até 19 dígitos)"},"expDate":{"type":"string","description":"Data de expiração do cartão (formato YYMM ou MMYY conforme configuração do HSM)"},"serviceCode":{"type":"string","description":"Service Code do cartão:\n- Valor do track → CVV tipo 1 (CVV1)\n- `000` → CVV tipo 2 (CVV2)\n- `999` → CVV dinâmico (dCVV)\n"}}}}}}
```
## The SuperGenerateCvInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield CVV API","version":"4.1.32"},"components":{"schemas":{"SuperGenerateCvInput":{"type":"object","required":["client_id","keyId","pan","expDate","serviceCodeArray"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave CVK no banco de dados"},"pan":{"type":"string","minLength":1,"maxLength":19,"description":"PAN do cartão (até 19 dígitos)"},"expDate":{"type":"string","description":"Data de expiração do cartão"},"serviceCodeArray":{"type":"array","items":{"type":"string"},"description":"Array de service codes para geração de múltiplos CVVs em uma única chamada.\nCada elemento gera um CVV correspondente em `retMultiValue`.\n"}}}}}}
```
## The ValidateCvInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield CVV API","version":"4.1.32"},"components":{"schemas":{"ValidateCvInput":{"allOf":[{"$ref":"#/components/schemas/CvvInputBase"},{"type":"object","required":["cv"],"properties":{"cv":{"type":"string","minLength":3,"maxLength":3,"pattern":"^[0-9]+$","description":"CVV/CVC a ser validado (exatamente 3 dígitos numéricos)"},"dynCv":{"type":"string","nullable":true,"description":"CVV dinâmico (usado apenas para serviceCode `999`)"}}}]},"CvvInputBase":{"type":"object","required":["client_id","keyId","pan","expDate","serviceCode"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave CVK no banco de dados"},"pan":{"type":"string","minLength":1,"maxLength":19,"description":"PAN do cartão (até 19 dígitos)"},"expDate":{"type":"string","description":"Data de expiração do cartão (formato YYMM ou MMYY conforme configuração do HSM)"},"serviceCode":{"type":"string","description":"Service Code do cartão:\n- Valor do track → CVV tipo 1 (CVV1)\n- `000` → CVV tipo 2 (CVV2)\n- `999` → CVV dinâmico (dCVV)\n"}}}}}}
```
## The ReturnSingle object
```json
{"openapi":"3.0.3","info":{"title":"PayShield CVV API","version":"4.1.32"},"components":{"schemas":{"ReturnSingle":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","nullable":true,"description":"Valor de retorno simples"},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retDescription":{"type":"string","description":"Descrição do resultado"}}}}}}
```
## The ReturnMultiValue object
```json
{"openapi":"3.0.3","info":{"title":"PayShield CVV API","version":"4.1.32"},"components":{"schemas":{"ReturnMultiValue":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","nullable":true},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Array com os CVVs gerados — um por service code enviado"},"retValid":{"type":"boolean"},"retDescription":{"type":"string"}}}}}}
```
## The ReturnError object
```json
{"openapi":"3.0.3","info":{"title":"PayShield CVV API","version":"4.1.32"},"components":{"schemas":{"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `500`: Erro interno\n- `400`: Requisição inválida\n- `155`: Chave não encontrada no banco de dados\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDescription":{"type":"string","description":"Descrição do erro"}}}}}}
```
---
# 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/hop-api/docs/cvv.md?ask=&goal=
```
`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.