> 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/referencia-da-api-cvv.md).
# Referência da API — CVV
Esta secção detalha os três endpoints responsáveis pelo ciclo de vida do CVV estático (o código impresso no plástico ou gravado na tarja magnética e no chip). Estas operações utilizam chaves do tipo CVK.
## Gerar CVV/CVC
> Gera o CVV/CVC (Card Verification Value/Code) para um cartão.\
> Retorna o valor gerado em \`retValue\`.\
> Em caso de erro, retorna os campos de erro (\`retCode\` e \`retDesc\`).
```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://apivin.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"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retDesc":{"type":"string","description":"Descrição do resultado"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `01`: Falha na verificação do CVV / criptograma\n- `05`: Scheme, Version ID ou Key Derivation Method não reconhecido\n- `06`: Valor YHHHHCC inválido\n- `10`: Erro de paridade na chave CVK A/B ou MK\n- `27`: CVK não é double length\n- `52`: Discretionary Data CVS inválido\n- `68`: Comando desabilitado\n- `E9`: Valor de máscara CVC3 inválido\n- `EA`: Modified PSN Flag inválido\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDesc":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldCVV/GenerateCV":{"post":{"tags":["CVV"],"summary":"Gerar CVV/CVC","description":"Gera o CVV/CVC (Card Verification Value/Code) para um cartão.\nRetorna o valor gerado em `retValue`.\nEm caso de erro, retorna os campos de erro (`retCode` e `retDesc`).\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","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"}}}}}}}}}
```
## Gerar múltiplos CVV/CVC
> Versão estendida do GenerateCV que aceita um array de service codes (\`serviceCodeArray\`)\
> e retorna um CVV/CVC gerado para cada service code em \`retMultiValue\`.\
> \
> Útil para gerar CVV1, CVV2 e iCVV de um mesmo cartão em uma única chamada.
```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://apivin.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"},"retDesc":{"type":"string"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `01`: Falha na verificação do CVV / criptograma\n- `05`: Scheme, Version ID ou Key Derivation Method não reconhecido\n- `06`: Valor YHHHHCC inválido\n- `10`: Erro de paridade na chave CVK A/B ou MK\n- `27`: CVK não é double length\n- `52`: Discretionary Data CVS inválido\n- `68`: Comando desabilitado\n- `E9`: Valor de máscara CVC3 inválido\n- `EA`: Modified PSN Flag inválido\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDesc":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldCVV/SuperGenerateCV":{"post":{"tags":["CVV"],"summary":"Gerar múltiplos CVV/CVC","description":"Versão estendida do GenerateCV que aceita um array de service codes (`serviceCodeArray`)\ne retorna um CVV/CVC gerado para cada service code em `retMultiValue`.\n\nÚtil para gerar CVV1, CVV2 e iCVV de um mesmo cartão em uma única chamada.\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","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"}}}}}}}}}
```
## Validar CVV/CVC
> Valida o CVV/CVC de um cartão.\
> Retorna \`true\` em \`retValid\` se o CVV for válido, \`false\` caso contrário.\
> \
> O campo \`serviceCode\` define o tipo de CVV:\
> \- Valor do track → CVV tipo 1 (CVV1)\
> \- \`000\` → CVV tipo 2 (CVV2)\
> \- \`999\` → CVV dinâmico (dCVV)\
> \
> Em caso de erro, retorna os campos de erro (\`retCode\` e \`retDesc\`).
```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://apivin.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"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retDesc":{"type":"string","description":"Descrição do resultado"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `01`: Falha na verificação do CVV / criptograma\n- `05`: Scheme, Version ID ou Key Derivation Method não reconhecido\n- `06`: Valor YHHHHCC inválido\n- `10`: Erro de paridade na chave CVK A/B ou MK\n- `27`: CVK não é double length\n- `52`: Discretionary Data CVS inválido\n- `68`: Comando desabilitado\n- `E9`: Valor de máscara CVC3 inválido\n- `EA`: Modified PSN Flag inválido\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDesc":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldCVV/ValidateCV":{"post":{"tags":["CVV"],"summary":"Validar CVV/CVC","description":"Valida o CVV/CVC de um cartão.\nRetorna `true` em `retValid` se o CVV for válido, `false` caso contrário.\n\nO campo `serviceCode` define o tipo de CVV:\n- Valor do track → CVV tipo 1 (CVV1)\n- `000` → CVV tipo 2 (CVV2)\n- `999` → CVV dinâmico (dCVV)\n\nEm caso de erro, retorna os campos de erro (`retCode` e `retDesc`).\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","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"}}}}}}}}}
```
## Verificar CVV/CVC dinâmico
> Verifica o CVV/CVC dinâmico (dCVV/CVC3) de um cartão para transações contactless e chip.\
> Suporta múltiplas bandeiras: Visa (DCVV), MasterCard (CVC3/PINCVC3), American Express (ExpressPay) e Discover (ZIP DCVV).\
> \
> Retorna \`true\` em \`retValid\` se o CVV dinâmico for válido.\
> Em caso de erro, retorna os campos de erro (\`retCode\` e \`retDesc\`).\
> \
> O comportamento varia conforme o campo \`brand\` e \`dynCvVers\`:\
> \- \*\*Visa\*\* (\`brand: "Visa"\`, \`dynCvVers: 0\`): requer \`expDate\`, \`serviceCode\`, \`atc\`, \`dynCv\`\
> \- \*\*MasterCard\*\* (\`brand: "MasterCard"\`): requer \`ivcvc3\` ou \`trackData\` dependendo da versão\
> \- \*\*American Express\*\* (\`brand: "American Express"\`, \`dynCvVers: 0\`): suporte básico\
> \- \*\*Discover\*\* (\`brand: "Discover"\`): suporte básico
```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://apivin.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":{"VerifyDynCvInput":{"type":"object","required":["client_id","keyId","dynCv","pan","expDate","serviceCode","brand","dynCvVers","kdm","atc"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave MKAC no banco de dados"},"dynCv":{"type":"string","description":"CVV/CVC dinâmico a ser verificado (3N para DCVV ou 5A para CVC3/PINCVC3)"},"pan":{"type":"string","description":"PAN do cartão"},"expDate":{"type":"string","description":"Data de expiração do cartão"},"serviceCode":{"type":"string","description":"Service Code do cartão"},"brand":{"type":"string","enum":["Visa","MasterCard","American Express","Discover"],"description":"Bandeira do cartão — determina o esquema de verificação utilizado"},"dynCvVers":{"type":"integer","description":"Versão do CVV dinâmico. Varia conforme a bandeira:\n- **Visa**: `0` (DCVV)\n- **MasterCard**: `0` (CVC3 com IVCVC3), `1` (CVC3 com PSN+IVCVC3), `2` (CVC3 com track data), `3` (PINCVC3)\n- **American Express**: `0` (ExpressPay 2.0)\n- **Discover**: `0` (ZIP DCVV), `1` (ZIP DCVV Plus)\n"},"kdm":{"type":"string","description":"Método de derivação de chave:\n- `A`: EMV 4.1 Book 2 Option A\n- `B`: EMV 4.1 Book 2 Option B\n- `2`: 16-byte AUKDCVV (apenas Discover)\n- `3`: 24-byte AUKDCVV (apenas Discover)\n"},"atc":{"type":"string","description":"Application Transaction Counter (6N para Visa, 5N para MasterCard)"},"psn":{"type":"string","nullable":true,"description":"PAN Sequence Number — obrigatório para MasterCard versões 1 e 2, e American Express"},"un":{"type":"string","nullable":true,"description":"Unpredictable Number — obrigatório para MasterCard"},"ivcvc3":{"type":"string","nullable":true,"description":"Issuer proprietary static data element — obrigatório para MasterCard versões 0 e 1"},"trackDataLen":{"type":"integer","nullable":true,"description":"Comprimento dos dados de track — obrigatório para MasterCard versões 2 e 3"},"trackData":{"type":"string","nullable":true,"description":"Dados estáticos do track 1 ou 2 — obrigatório para MasterCard versões 2 e 3"}}},"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"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retDesc":{"type":"string","description":"Descrição do resultado"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `01`: Falha na verificação do CVV / criptograma\n- `05`: Scheme, Version ID ou Key Derivation Method não reconhecido\n- `06`: Valor YHHHHCC inválido\n- `10`: Erro de paridade na chave CVK A/B ou MK\n- `27`: CVK não é double length\n- `52`: Discretionary Data CVS inválido\n- `68`: Comando desabilitado\n- `E9`: Valor de máscara CVC3 inválido\n- `EA`: Modified PSN Flag inválido\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDesc":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldCVV/VerifyDynCV":{"post":{"tags":["CVV"],"summary":"Verificar CVV/CVC dinâmico","description":"Verifica o CVV/CVC dinâmico (dCVV/CVC3) de um cartão para transações contactless e chip.\nSuporta múltiplas bandeiras: Visa (DCVV), MasterCard (CVC3/PINCVC3), American Express (ExpressPay) e Discover (ZIP DCVV).\n\nRetorna `true` em `retValid` se o CVV dinâmico for válido.\nEm caso de erro, retorna os campos de erro (`retCode` e `retDesc`).\n\nO comportamento varia conforme o campo `brand` e `dynCvVers`:\n- **Visa** (`brand: \"Visa\"`, `dynCvVers: 0`): requer `expDate`, `serviceCode`, `atc`, `dynCv`\n- **MasterCard** (`brand: \"MasterCard\"`): requer `ivcvc3` ou `trackData` dependendo da versão\n- **American Express** (`brand: \"American Express\"`, `dynCvVers: 0`): suporte básico\n- **Discover** (`brand: \"Discover\"`): suporte básico\n","operationId":"verifyDynCV","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyDynCvInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnSingle"}}}},"400":{"description":"Requisição inválida","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"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retDesc":{"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"},"retDesc":{"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- `01`: Falha na verificação do CVV / criptograma\n- `05`: Scheme, Version ID ou Key Derivation Method não reconhecido\n- `06`: Valor YHHHHCC inválido\n- `10`: Erro de paridade na chave CVK A/B ou MK\n- `27`: CVK não é double length\n- `52`: Discretionary Data CVS inválido\n- `68`: Comando desabilitado\n- `E9`: Valor de máscara CVC3 inválido\n- `EA`: Modified PSN Flag inválido\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDesc":{"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/landing-page/modulo-cvv/referencia-da-api-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.