CVV

Endpoints do serviço ws-hop-api-cvv

CVV Generate CV Module

post

Returns the CV (Card Validation Value / Code) in (retValue).

Authorizations

bearerAuth

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

application/json

client_idinteger · int64 · min: 1Required

Identificador do cliente

Example: 99

keyIdstringRequired

Alias/identificador da chave CVK no banco de dados

Example: client-99-key-id-XXXXX-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: 1232

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

retValidbooleanOptional

Indica se a operação foi bem-sucedida

Example: true

retDescriptionstringOptional

Descrição do resultado

Example: OK

400

Requisição inválida — campo obrigatório ausente ou formato incorreto

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: api-hext.first-tech.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 115

{
  "client_id": 99,
  "keyId": "client-99-key-id-XXXXX-CVK",
  "pan": "4234567890123456",
  "expDate": "1232",
  "serviceCode": "501"
}

{
  "retCode": 0,
  "retValid": true,
  "retValue": "515",
  "retDescription": "OK"
}

CVV Generate CV Module

post

Returns the CVs (Card Validation Value / Code) in (retMultiValue).

Authorizations

bearerAuth

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

application/json

client_idinteger · int64 · min: 1Required

Identificador do cliente

Example: 99

keyIdstringRequired

Alias/identificador da chave CVK no banco de dados

Example: client-99-key-id-XXXXX-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: 1232

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

retDescriptionstringOptionalExample: OK

400

Requisição inválida — campo obrigatório ausente ou formato incorreto

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: api-hext.first-tech.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 135

{
  "client_id": 99,
  "keyId": "client-99-key-id-XXXXXX-CVK",
  "pan": "4234567890123456",
  "expDate": "1133",
  "serviceCodeArray": [
    "825",
    "826",
    "827"
  ]
}

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

CVV Dynamic Module

post

Returns OK(true) or Not-Ok(false) in (retValid), in case of error, it returns details in the Error fields (retCode and RetDescription).

Authorizations

bearerAuth

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

application/json

client_idinteger · int64 · min: 1Required

Identificador do cliente

Example: 99

keyIdstringRequired

Alias/identificador da chave CVK no banco de dados

Example: client-99-key-id-XXXXX-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: 1232

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

retValidbooleanOptional

Indica se a operação foi bem-sucedida

Example: true

retDescriptionstringOptional

Descrição do resultado

Example: OK

400

Requisição inválida — campo obrigatório ausente ou formato incorreto

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: api-hext.first-tech.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 126

{
  "client_id": 99,
  "keyId": "client-99-key-id-XXXXX-CVK",
  "cv": "231",
  "pan": "2444123456789012",
  "expDate": "1232",
  "serviceCode": "101"
}

{
  "retCode": 0,
  "retValid": true,
  "retValue": "CVV Validated",
  "retDescription": "OK"
}