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

post

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).

Authorizations

bearerAuth

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

application/json

client_idinteger · int64 · min: 1Required

Identificador do cliente

Example: 42

keyIdstringRequired

Alias/identificador da chave CVK no banco de dados

Example: client-42-XX-key-id-XXXX-CVK

panstring · min: 1 · max: 19Required

PAN do cartão (até 19 dígitos)

Example: 4234567890123456

expDatestringRequired

Data de expiração do cartão (formato YYMM ou MMYY conforme configuração do HSM)

Example: 825

serviceCodestringRequired

Service Code do cartão:

• Valor do track → CVV tipo 1 (CVV1)
• 000 → CVV tipo 2 (CVV2)
• 999 → CVV dinâmico (dCVV)

Example: 501

Responses

200

Operação realizada com sucesso

application/json

retCodeintegerOptional

Código de retorno. 0 = sucesso, outros valores indicam erro

Example: 0

retValuestring · nullableOptional

Valor de retorno simples

Example: CVV Validated

retMultiValueany · nullableOptional

retValidbooleanOptional

Indica se a operação foi bem-sucedida

Example: true

retDescstringOptional

Descrição do resultado

Example: No error

400

Requisição inválida

application/json

401

Não autorizado — token Bearer ausente ou inválido

404

Chave não encontrada no banco de dados

application/json

500

Erro interno do servidor

application/json

post/v4/PayShieldCVV/GenerateCV

HTTPcURLJavaScriptPython

POST /v4/PayShieldCVV/GenerateCV HTTP/1.1
Host: apivin.first-tech.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 116

{
  "client_id": 42,
  "keyId": "client-42-XX-key-id-XXXX-CVK",
  "pan": "4234567890123456",
  "expDate": "825",
  "serviceCode": "501"
}

{
  "retCode": 0,
  "retValue": "515",
  "retMultiValue": null,
  "retValid": true,
  "retDesc": "OK"
}

Gerar múltiplos CVV/CVC

post

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.

Authorizations

bearerAuth

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

application/json

client_idinteger · int64 · min: 1Required

Identificador do cliente

Example: 42

keyIdstringRequired

Alias/identificador da chave CVK no banco de dados

Example: client-42-XX-key-id-XXXX-CVK

panstring · min: 1 · max: 19Required

PAN do cartão (até 19 dígitos)

Example: 4234567890123456

expDatestringRequired

Data de expiração do cartão

Example: 825

serviceCodeArraystring[]Required

Array de service codes para geração de múltiplos CVVs em uma única chamada. Cada elemento gera um CVV correspondente em retMultiValue.

Example: ["501","201","999"]

Responses

200

Operação realizada com sucesso

application/json

retCodeintegerOptional

Código de retorno. 0 = sucesso, outros valores indicam erro

Example: 0

retValuestring · nullableOptional

retMultiValuestring[] · nullableOptional

Array com os CVVs gerados — um por service code enviado

Example: ["515","653","128"]

retValidbooleanOptionalExample: true

retDescstringOptionalExample: OK

400

Requisição inválida

application/json

401

Não autorizado — token Bearer ausente ou inválido

404

Chave não encontrada no banco de dados

application/json

500

Erro interno do servidor

application/json

post/v4/PayShieldCVV/SuperGenerateCV

HTTPcURLJavaScriptPython

POST /v4/PayShieldCVV/SuperGenerateCV HTTP/1.1
Host: apivin.first-tech.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 135

{
  "client_id": 42,
  "keyId": "client-42-XX-key-id-XXXX-CVK",
  "pan": "4234567890123456",
  "expDate": "825",
  "serviceCodeArray": [
    "501",
    "201",
    "999"
  ]
}

{
  "retCode": 0,
  "retValue": null,
  "retMultiValue": [
    "515",
    "653",
    "128"
  ],
  "retValid": true,
  "retDesc": "OK"
}

Validar CVV/CVC

post

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).

Authorizations

bearerAuth

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

application/json

client_idinteger · int64 · min: 1Required

Identificador do cliente

Example: 42

keyIdstringRequired

Alias/identificador da chave CVK no banco de dados

Example: client-42-XX-key-id-XXXX-CVK

panstring · min: 1 · max: 19Required

PAN do cartão (até 19 dígitos)

Example: 4234567890123456

expDatestringRequired

Data de expiração do cartão (formato YYMM ou MMYY conforme configuração do HSM)

Example: 825

serviceCodestringRequired

Service Code do cartão:

• Valor do track → CVV tipo 1 (CVV1)
• 000 → CVV tipo 2 (CVV2)
• 999 → CVV dinâmico (dCVV)

Example: 501

cvstring · min: 3 · max: 3Required

CVV/CVC a ser validado (exatamente 3 dígitos numéricos)

Example: 231Pattern: ^[0-9]+$

dynCvstring · nullableOptional

CVV dinâmico (usado apenas para serviceCode 999)

Responses

200

Operação realizada com sucesso

application/json

retCodeintegerOptional

Código de retorno. 0 = sucesso, outros valores indicam erro

Example: 0

retValuestring · nullableOptional

Valor de retorno simples

Example: CVV Validated

retMultiValueany · nullableOptional

retValidbooleanOptional

Indica se a operação foi bem-sucedida

Example: true

retDescstringOptional

Descrição do resultado

Example: No error

400

Requisição inválida

application/json

401

Não autorizado — token Bearer ausente ou inválido

404

Chave não encontrada no banco de dados

application/json

500

Erro interno do servidor

application/json

post/v4/PayShieldCVV/ValidateCV

HTTPcURLJavaScriptPython

POST /v4/PayShieldCVV/ValidateCV HTTP/1.1
Host: apivin.first-tech.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 128

{
  "client_id": 42,
  "keyId": "client-42-key-id-XXX-MKAC",
  "cv": "231",
  "pan": "2444123456789012345",
  "expDate": "8701",
  "serviceCode": "101"
}

{
  "retCode": 0,
  "retValue": "CVV Validated",
  "retMultiValue": null,
  "retValid": true,
  "retDesc": "No error"
}

Verificar CVV/CVC dinâmico

post

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

Authorizations

bearerAuth

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

application/json

client_idinteger · int64 · min: 1Required

Identificador do cliente

Example: 42

keyIdstringRequired

Alias/identificador da chave MKAC no banco de dados

Example: client-42-key-id-XXX-MKAC

dynCvstringRequired

CVV/CVC dinâmico a ser verificado (3N para DCVV ou 5A para CVC3/PINCVC3)

Example: 019

panstringRequired

PAN do cartão

Example: 2499100031640500

expDatestringRequired

Data de expiração do cartão

Example: 0087

serviceCodestringRequired

Service Code do cartão

Example: 011

brandstring · enumRequired

Bandeira do cartão — determina o esquema de verificação utilizado

Example: VisaPossible values:

dynCvVersintegerRequired

Versão do CVV dinâmico. Varia conforme a bandeira:

• Visa: 0 (DCVV)
• MasterCard: 0 (CVC3 com IVCVC3), 1 (CVC3 com PSN+IVCVC3), 2 (CVC3 com track data), 3 (PINCVC3)
• American Express: 0 (ExpressPay 2.0)
• Discover: 0 (ZIP DCVV), 1 (ZIP DCVV Plus)

Example: 0

kdmstringRequired

Método de derivação de chave:

• A: EMV 4.1 Book 2 Option A
• B: EMV 4.1 Book 2 Option B
• 2: 16-byte AUKDCVV (apenas Discover)
• 3: 24-byte AUKDCVV (apenas Discover)

Example: A

atcstringRequired

Application Transaction Counter (6N para Visa, 5N para MasterCard)

Example: 010008

psnstring · nullableOptional

PAN Sequence Number — obrigatório para MasterCard versões 1 e 2, e American Express

unstring · nullableOptional

Unpredictable Number — obrigatório para MasterCard

ivcvc3string · nullableOptional

Issuer proprietary static data element — obrigatório para MasterCard versões 0 e 1

trackDataLeninteger · nullableOptional

Comprimento dos dados de track — obrigatório para MasterCard versões 2 e 3

trackDatastring · nullableOptional

Dados estáticos do track 1 ou 2 — obrigatório para MasterCard versões 2 e 3

Responses

200

Operação realizada com sucesso

application/json

retCodeintegerOptional

Código de retorno. 0 = sucesso, outros valores indicam erro

Example: 0

retValuestring · nullableOptional

Valor de retorno simples

Example: CVV Validated

retMultiValueany · nullableOptional

retValidbooleanOptional

Indica se a operação foi bem-sucedida

Example: true

retDescstringOptional

Descrição do resultado

Example: No error

400

Requisição inválida

application/json

401

Não autorizado — token Bearer ausente ou inválido

404

Chave não encontrada no banco de dados

application/json

500

Erro interno do servidor

application/json

post/v4/PayShieldCVV/VerifyDynCV

HTTPcURLJavaScriptPython

POST /v4/PayShieldCVV/VerifyDynCV HTTP/1.1
Host: apivin.first-tech.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 254

{
  "client_id": 42,
  "keyId": "client-42-key-id-XXX-MKAC",
  "dynCv": "019",
  "pan": "2499100031640500",
  "expDate": "0087",
  "serviceCode": "011",
  "brand": "Visa",
  "dynCvVers": 0,
  "kdm": "A",
  "atc": "010008",
  "psn": null,
  "un": null,
  "ivcvc3": null,
  "trackDataLen": null,
  "trackData": null
}

{
  "retCode": 0,
  "retValue": "CVV Validated",
  "retMultiValue": null,
  "retValid": true,
  "retDesc": "No error"
}