Referência API - PIN

Validar PIN

post

Valida o PIN do portador do cartão comparando o PinBlock recebido com o PIN armazenado no HSM. Retorna true em retValid se o PIN for válido, false caso contrário. Em caso de erro, retorna os campos de erro (retCode e retDescription).

Authorizations

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

client_idinteger · int64 · min: 1Required

Identificador do cliente

Example: 42

keyIdstringRequired

Alias/identificador da chave TPK ou ZPK no banco de dados

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

hPibBlockstringRequired

PinBlock em formato Hexadecimal

Example: 65CDF8DA33954DA41C944AD68AA75AB4

pibBlockFmtstringRequired

Formato do PinBlock. Valores válidos: 01, 02, 03, 04, 05, 34, 35, 41, 42, 47, 48

Example: 48

hPinHoststring · nullableOptional

PIN Host em formato Hexadecimal (usado para validação contra PIN armazenado)

Example: MFA7DB4D986A8238EFB7E11A584459157

panstringRequired

PAN do cartão (16 a 19 dígitos)

Example: 1111222233334444

Responses

200

Operação realizada com sucesso

application/json

retCodeintegerOptional

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

Example: 0

retValuestringOptional

Valor de retorno simples

Example: PIN Validated

retMultiValueany · nullableOptional

retValidbooleanOptional

Indica se a operação foi bem-sucedida

Example: true

retDescstringOptional

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/PayShieldPin/ValidatePin

POST /v4/PayShieldPin/ValidatePin HTTP/1.1
Host: apivin.first-tech.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 189

{
  "client_id": 42,
  "keyId": "client-42-key-id-XXX-TPK",
  "hPibBlock": "65CDF8DA33954DA41C944AD68AA75AB4",
  "pibBlockFmt": "48",
  "hPinHost": "MFA7DB4D986A8238EFB7E11A584459157",
  "pan": "1111222233334444"
}

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

---

Traduzir PIN

post

Traduz um PinBlock de uma chave de origem (keyIdSrc) para uma chave de destino (keyIdDst). Suporta chaves do tipo TPK, ZPK e BDK (DUKPT).

Retorna em retMultiValue:

• retMultiValue[0] = formato do PinBlock de destino

• retMultiValue[1] = PinBlock traduzido (sob a chave de destino)

• retMultiValue[2] = formato do PinBlock de origem

Em caso de erro, retorna os campos de erro (retCode e retDescription).

Authorizations

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

client_idinteger · int64 · min: 1Required

Identificador do cliente

Example: 42

keyIdSrcstringRequired

Alias/identificador da chave de origem (TPK, ZPK ou BDK)

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

hPibBlockSrcstringRequired

PinBlock de origem em formato alfanumérico (a-z, A-Z, 0-9)

Example: DD147680B1F1FA43

pibBlockFmtSrcstringRequired

Formato do PinBlock de origem. Valores válidos: 01, 02, 03, 04, 05, 34, 35, 41, 42, 47, 48

Example: 01

hPinHoststring · nullableOptional

PIN Host em formato Hexadecimal (opcional)

keyIdDststringRequired

Alias/identificador da chave de destino (TPK, ZPK ou BDK)

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

pibBlockFmtDststringRequired

Formato do PinBlock de destino. Valores válidos: 01, 02, 03, 04, 05, 34, 35, 41, 42, 47, 48

Example: 01

panstringRequired

PAN do cartão de origem (16 a 19 dígitos)

Example: 1234000001234864

ksn_descstring · nullableOptional

Descritor KSN da chave de origem — necessário apenas se keyIdSrc for do tipo BDK (DUKPT)

Example: 505

ksnstring · nullableOptional

KSN da chave de origem — necessário apenas se keyIdSrc for do tipo BDK (DUKPT)

Example: 876543210E20004

pan_dststring · nullableOptional

PAN do cartão de destino (16 a 19 dígitos) — necessário quando o PAN de destino difere do de origem

ksn_desc_dststring · nullableOptional

Descritor KSN da chave de destino — necessário apenas se keyIdDst for do tipo BDK (DUKPT)

ksn_dststring · nullableOptional

KSN da chave de destino — necessário apenas se keyIdDst for do tipo BDK (DUKPT)

Responses

200

Operação realizada com sucesso

application/json

retCodeintegerOptional

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

Example: 0

retValuestringOptional

Valor de retorno simples (geralmente vazio em sucesso)

retMultiValuestring[] · nullableOptional

Array com os valores de retorno da operação TranslatePin:

• [0] = formato do PinBlock de destino
• [1] = PinBlock traduzido (sob a chave de destino)
• [2] = formato do PinBlock de origem

Example: ["04","AFA6E4706993CB9F","01"]

retValidbooleanOptional

Indica se a operação foi bem-sucedida

Example: true

retDescstringOptional

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/PayShieldPin/TranslatePin

POST /v4/PayShieldPin/TranslatePin HTTP/1.1
Host: apivin.first-tech.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 302

{
  "client_id": 42,
  "keyIdSrc": "client-42-key-id-XXX-BDK",
  "hPibBlockSrc": "DD147680B1F1FA43",
  "pibBlockFmtSrc": "01",
  "hPinHost": null,
  "keyIdDst": "client-42-key-id-XXX-ZPK",
  "pibBlockFmtDst": "01",
  "pan": "1234000001234864",
  "ksn_desc": "505",
  "ksn": "876543210E20004",
  "pan_dst": null,
  "ksn_desc_dst": null,
  "ksn_dst": null
}

{
  "retCode": 0,
  "retValue": "",
  "retMultiValue": [
    "04",
    "AFA6E4706993CB9F",
    "01"
  ],
  "retValid": true,
  "retDesc": "OK"
}