Integração e Exemplos Práticos

Esta secção detalha como os endpoints do módulo CVV se encaixam na arquitetura real de um emissor ou processador de cartões, apresentando os fluxos recomendados, boas práticas de segurança e exemplos de código prontos a utilizar.

Fluxo Típico: Emissão de Cartão

No momento da personalização e emissão de um novo cartão, o emissor necessita tipicamente de gerar os três valores de CVV de uma só vez .

O fluxo recomendado é o seguinte:

1. Autenticação: Obter o token JWT via Auth0 (utilizando o grant client_credentials), que é válido tipicamente por 24 horas.

2. Geração em Lote: Invocar o endpoint SuperGenerateCV enviando o array ["<track>", "000", "999"] no campo serviceCodeArray para obter o CVV1, CVV2 e dCVV numa única chamada.

3. Persistência e Roteamento: Persistir os valores no sistema do emissor da seguinte forma:

   • O CVV1 segue para gravação na tarja/chip.

   • O CVV2 segue para a gráfica (impressão no plástico).

   • O dCVV é guardado apenas no servidor para validação em transações futuras.

4. Tratamento da Resposta: Verificar se retCode = 0 e retValid = true. Em caso de falha, consultar o catálogo de erros para diagnóstico.

Fluxo Típico: Autorização de Transação

Para transações e-commerce/MOTO (Card-Not-Present) que exigem o CVV2:

1. Autenticação: Obter ou recuperar do cache o token JWT do Auth0 .

2. Validação Estática: Invocar o ValidateCV enviando serviceCode = "000" e o cv preenchido no checkout pelo portador.

3. Decisão de Negócio: Avaliar o campo retValid:

   • true: Seguir com a autorização da compra.

   • false: Recusar a transação ou solicitar nova digitação do código .

Para transações presenciais (Chip/Contactless) com dCVV:

• Substituir o passo 2 pelo uso do endpoint VerifyDynCV, preenchendo os campos dependentes da bandeira (como brand, dynCvVers, atc, etc.) recebidos no momento da aproximação.

Boas Práticas de Integração

Antes de colocar o código em produção, valide se a sua aplicação cumpre as seguintes diretrizes essenciais de segurança e resiliência:

Categoria	Boas Práticas
Autenticação	Cache do JWT: Os tokens Auth0 possuem validade longa. Não solicite um novo token a cada chamada de CVV; isso introduz latência desnecessária e pode esgotar os rate limits do serviço de autenticação.
Resiliência	Idempotência Nativa: Os endpoints GenerateCV e SuperGenerateCV são determinísticos. Para os mesmos inputs (PAN, expDate, serviceCode e chave), retornarão sempre o mesmo CVV. Isto permite o replay seguro de requisições em caso de timeout de rede .
Segurança	Higienização de Logs: Jamais registe o CVV em texto claro nos logs da sua aplicação. Registe apenas o client_id, keyId, retCode e retDesc para auditoria. Nunca guarde o PAN completo, o campo cv de entrada ou o retValue contendo a resposta .
Políticas de Retry	Como tratar erros: Erros 500 e 504 podem sofrer tentativas repetidas (retry) com backoff exponencial. Erros 400 (input inválido), 401 e 404 (chave inexistente) não devem ser retentados sem que a aplicação corrija o dado de origem .

Exemplos de Código

Estes snippets demonstram a invocação prática dos endpoints.

cURL — Gerar CVV2 (GenerateCV)

Bash
curl -X POST \
  https://apivin.first-tech.net/v4/PayShieldCVV/GenerateCV \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 42,
    "keyId": "client-42-XX-key-id-XXXX-CVK",
    "pan": "4234567890123456",
    "expDate": "825",
    "serviceCode": "000"
}'

Python — Validar CVV2 no Checkout (ValidateCV)

Python

Python
import requests

url = "https://apivin.first-tech.net/v4/PayShieldCVV/ValidateCV"
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
}
payload = {
    "client_id": 42,
    "keyId": "client-42-XX-key-id-XXXX-CVK",
    "pan": "4234567890123456",
    "expDate": "825",
    "serviceCode": "000",
    "cv": "515"
}

r = requests.post(url, json=payload, headers=headers, timeout=10)
data = r.json()

if data.get("retValid"):
    print("CVV válido - seguir com autorização")
else:
    print(f"CVV inválido - código {data.get('retCode')}: {data.get('retDesc')}")

Node.js — Gerar os 3 CVVs na Emissão (SuperGenerateCV)

JavaScript
const axios = require("axios");

async function gerarCvvsEmissao(token, pan, expDate, trackServiceCode) {
  const url = "https://apivin.first-tech.net/v4/PayShieldCVV/SuperGenerateCV";
  const payload = {
    client_id: 42,
    keyId: "client-42-XX-key-id-XXXX-CVK",
    pan,
    expDate,
    serviceCodeArray: [trackServiceCode, "000", "999"],
  };

  const { data } = await axios.post(url, payload, {
    headers: { Authorization: `Bearer ${token}` },
    timeout: 10000,
  });

  if (!data.retValid) {
    throw new Error(`HSM retCode=${data.retCode}: ${data.retDesc}`);
  }

  const [cvv1, cvv2, dcvvSeed] = data.retMultiValue;
  return { cvv1, cvv2, dcvvSeed };
}