Gera (ou reaproveita) um CVV dinâmico válido por um curto período (default 3 min) e devolve em claro no body. Fluxo Get-or-Create: se já existe CVV ativo na Autra, reusa; senão, cria com a TTL solicitada.
PCI: o CVV em claro só vive na resposta desta request. Não persistimos nem logamos. Response carrega Cache-Control: no-store.
Pré-condições do cartão:
- Tipo
VIRTUAL(cartão físico retornaCARD_PHYSICAL) - Status
NORMAL(ativado —BLOCKED/CANCELEDretornamCARD_NOT_ACTIVE)
Auth: BearerAuth + header X-Account-Pin (6 dígitos, mesma porta do TED OUT / PAN reveal).
Rate-limit: 60 reveals/hora por cartão (separado do PAN reveal). Excedido → REVEAL_RATE_LIMITED.
Fluxo recomendado no app:
- Portador toca "mostrar CVV" → chama este endpoint.
- Exibe
cvvna UI com countdown baseado emexpirationDate/ttlSeconds. - Ao sair da tela ou zerar o countdown →
DELETEneste mesmo path pra invalidar imediatamente.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
PIN_REQUIRED (header ausente) ou INVALID_EXPIRATION_DATE (TTL fora da janela).
PIN_INVALID — PIN não confere.
PIN_LOCKED — conta bloqueada por tentativas; ou token inválido.
CARD_NOT_FOUND — cartão não existe pra este tenant.
CARD_NOT_ISSUED— cartão ainda semdock_card_id.CARD_PHYSICAL— cartão é físico, dynamic CVV só funciona em virtual.CARD_NOT_ACTIVE— cartão está BLOCKED/CANCELED; ative primeiro.DYNAMIC_CVV_ALREADY_ACTIVE— raro (race); chameDELETEe tente de novo.
REVEAL_RATE_LIMITED — mais de 60 reveals neste cartão na última hora.
FEATURE_DISABLED — backend sem CARDS_RSA_KMS_KEY_ID.