Referência API - PAN

Autenticação

Todas as chamadas à API exigem o cabeçalho Authorization preenchido com um token Bearer JWT válido .

HTTP

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ii4uLiJ9...

Gerar PIN aleatório

post

Gera um PIN aleatório e retorna o PIN criptografado sob a LMK em retMultiValue[0]. 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

panstring · min: 12 · max: 19Required

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

Example: 1111222233334444

pinLengthinteger · min: 4 · max: 12Required

Comprimento do PIN a ser gerado (4 a 12 dígitos)

Example: 4

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

retMultiValuestring[] · nullableOptional

Array com os valores de retorno da operação

retValidbooleanOptional

Indica se a operação foi bem-sucedida

Example: true

retDescriptionstringOptional

Descrição do resultado

Example: No error

400

Requisição inválida

application/json

401

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

500

Erro interno do servidor

application/json

post/v4/PayShieldPan/GeneratePin

POST /v4/PayShieldPan/GeneratePin HTTP/1.1
Host: apivin.first-tech.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 55

{
  "client_id": 42,
  "pan": "1111222233334444",
  "pinLength": 4
}

{
  "retCode": 0,
  "retValue": "",
  "retMultiValue": [
    "M1F5A7C1B7B3FC5B15466A9B652A48270"
  ],
  "retValid": true,
  "retDescription": "No error"
}

Gerar PIN com chave do emissor

post

Gera um novo PIN e o criptografa com a chave do emissor (keyIdDb). Retorna o PIN gerado em retMultiValue.generatedPin. 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

panstringRequired

PAN do cartão

Example: 1111222233334444

pinLengthinteger · min: 4 · max: 12Required

Comprimento do PIN a ser gerado

Example: 4

keyIdDbstringRequired

Alias/identificador da chave ZPK do emissor no banco de dados

Example: client-4-key-id-253-ZPK-A1

Responses

200

Operação realizada com sucesso

application/json

retCodeintegerOptionalExample: 0

retValuestringOptionalExample: PIN Generated

retMultiValueobject · nullableOptional

Objeto com os valores de retorno (estrutura varia por operação)

retValidbooleanOptionalExample: true

retDescriptionstringOptionalExample: OK

400

Requisição inválida

application/json

401

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

500

Erro interno do servidor

application/json

post/v4/PayShieldPan/GeneratePinIssuerKey

POST /v4/PayShieldPan/GeneratePinIssuerKey HTTP/1.1
Host: apivin.first-tech.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 94

{
  "client_id": 42,
  "pan": "1111222233334444",
  "pinLength": 4,
  "keyIdDb": "client-4-key-id-253-ZPK-A1"
}

{
  "retCode": 0,
  "retValue": "PIN Generated",
  "retMultiValue": {
    "generatedPin": "B07A27355EAA47013E504A956BDBF412"
  },
  "retValid": true,
  "retDescription": "OK"
}

PIN Embossing — LMK (AES) para ZPK (3DES)

post

Traduz o PIN de criptografia sob a LMK (AES) para criptografia sob uma ZPK (3DES). Retorna o PinBlock traduzido em retMultiValue[0].

Chaves de criptografia AES só podem ser usadas com o formato de PinBlock 48 (ISO PIN Block Format 4).

Authorizations

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

client_idinteger · int64 · min: 1Required

Identificador do cliente

Example: 42

zpkKeyIdSrcstringRequired

Alias da chave de origem AES (LMK)

Example: client-42-key-id-022-BDK-AES-A3

zpkKeyIdDststringRequired

Alias da chave de destino 3DES (ZPK)

Example: client-42-key-id-020-BDK-3DES-T2

pinBlockSrcstring · min: 4 · max: 33Required

PinBlock de origem criptografado sob a chave AES

Example: 97A2DB61C1B4847F30A7A910FAEF59E6

panstring · min: 16 · max: 16Required

PAN do cartão (exatamente 16 dígitos)

Example: 1111222233334444

pinBlockFmtDststring · min: 2 · max: 2Required

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

Example: 01

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

retMultiValuestring[] · nullableOptional

Array com os valores de retorno da operação

retValidbooleanOptional

Indica se a operação foi bem-sucedida

Example: true

retDescriptionstringOptional

Descrição do resultado

Example: No error

400

Requisição inválida

application/json

401

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

500

Erro interno do servidor

application/json

post/v4/PayShieldPan/PinEmbossing

POST /v4/PayShieldPan/PinEmbossing HTTP/1.1
Host: apivin.first-tech.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 209

{
  "client_id": 42,
  "zpkKeyIdSrc": "client-42-key-id-022-BDK-AES-A3",
  "zpkKeyIdDst": "client-42-key-id-020-BDK-3DES-T2",
  "pinBlockSrc": "97A2DB61C1B4847F30A7A910FAEF59E6",
  "pan": "1111222233334444",
  "pinBlockFmtDst": "01"
}

{
  "retCode": 0,
  "retValue": "",
  "retMultiValue": [
    "MABCDEF0123456789ABCDEF0123456789"
  ],
  "retValid": true,
  "retDescription": "Ok"
}

PIN Internalization — ZPK (3DES) para LMK (AES)

post

Traduz o PIN de criptografia sob uma ZPK (3DES) para criptografia sob a LMK (AES). Retorna o PinBlock traduzido em retMultiValue[0].

Chaves 3DES não podem ser usadas com o formato de PinBlock 48 (ISO PIN Block Format 4).

Authorizations

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

client_idinteger · int64 · min: 1Required

Identificador do cliente

Example: 42

zpkKeyIdSrcstringRequired

Alias da chave de origem 3DES (ZPK)

Example: client-42-key-id-020-BDK-3DES-T2

zpkKeyIdDststringRequired

Alias da chave de destino AES (LMK)

Example: client-42-key-id-022-BDK-AES-A3

pinBlockSrcstring · min: 4 · max: 33Required

PinBlock de origem criptografado sob a chave 3DES

Example: 52FC2A62F61F947B4F7B1C6050F26B5C

pinBlockFmtSrcstringRequired

Formato do PinBlock de origem. Valores válidos: 01, 02, 03, 04, 05, 34, 35, 41, 42, 47 (formato 48 não é suportado para chaves 3DES)

Example: 01

panstring · min: 16 · max: 16Required

PAN do cartão (exatamente 16 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

retValuestring · nullableOptional

Valor de retorno simples

retMultiValuestring[] · nullableOptional

Array com os valores de retorno da operação

retValidbooleanOptional

Indica se a operação foi bem-sucedida

Example: true

retDescriptionstringOptional

Descrição do resultado

Example: No error

400

Requisição inválida

application/json

401

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

500

Erro interno do servidor

application/json

post/v4/PayShieldPan/PinInternalization

POST /v4/PayShieldPan/PinInternalization HTTP/1.1
Host: apivin.first-tech.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 209

{
  "client_id": 42,
  "zpkKeyIdSrc": "client-42-key-id-020-BDK-3DES-T2",
  "zpkKeyIdDst": "client-42-key-id-022-BDK-AES-A3",
  "pinBlockSrc": "52FC2A62F61F947B4F7B1C6050F26B5C",
  "pan": "1111222233334444",
  "pinBlockFmtSrc": "01"
}

{
  "retCode": 0,
  "retValue": "",
  "retMultiValue": [
    "MABCDEF0123456789ABCDEF0123456789"
  ],
  "retValid": true,
  "retDescription": "No error"
}

Traduzir PAN

post

Traduz o PIN criptografado sob a LMK de um PAN antigo para um PAN novo. O PIN do cliente permanece inalterado. Retorna o PIN re-criptografado com o novo PAN em retMultiValue[0].

Quando usando AES Key Block LMK, o PIN criptografado sob a LMK usa o formato Thales 48 (ISO PIN Block format 4).

Authorizations

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

client_idinteger · int64 · min: 1Required

Identificador do cliente

Example: 42

pinstring · max: 33Required

PIN criptografado sob a LMK

Example: M1F5A7C1B7B3FC5B15466A9B652A48270

oldPanstring · min: 12 · max: 19Required

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

Example: 1111222233334444

newPanstring · min: 12 · max: 19Required

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

Example: 4444333322221111

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

retMultiValuestring[] · nullableOptional

Array com os valores de retorno da operação

retValidbooleanOptional

Indica se a operação foi bem-sucedida

Example: true

retDescriptionstringOptional

Descrição do resultado

Example: No error

400

Requisição inválida

application/json

401

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

500

Erro interno do servidor

application/json

post/v4/PayShieldPan/TranslatePan

POST /v4/PayShieldPan/TranslatePan HTTP/1.1
Host: apivin.first-tech.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 114

{
  "client_id": 42,
  "pin": "M1F5A7C1B7B3FC5B15466A9B652A48270",
  "oldPan": "1111222233334444",
  "newPan": "4444333322221111"
}

{
  "retCode": 0,
  "retValue": "",
  "retMultiValue": [
    "MB3F1F5A7C1B7C5B15466A9B652B48270"
  ],
  "retValid": true,
  "retDescription": "Ok"
}

Traduzir PIN — LMK (AES) para ZPK (AES)

post

Traduz o PIN de criptografia sob a LMK (AES) para criptografia sob uma ZPK (AES). Retorna o PinBlock traduzido em retMultiValue[0].

Quando usado com Variant LMK ou 3DES Key Block LMK, o PIN criptografado sob a LMK sempre usará formato não-ISO.

Authorizations

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

client_idinteger · int64 · min: 1Required

Identificador do cliente

Example: 42

keyIdstringRequired

Alias/identificador da chave ZPK de destino

Example: client-42-key-id-020-ZPK-AES-A3

pinstring · max: 33Required

PIN criptografado sob a LMK

Example: MABCDEF0123456789ABCDEF0123456789

panstringRequired

PAN do cartão

Example: 1111222233334444

formatCodeinteger · max: 4Required

Código de formato do PinBlock de destino:

0 → formato Thales 01
1 → formato Thales 05
3 → formato Thales 47
4 (padrão) → formato Thales 48

Example: 4

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

retMultiValuestring[] · nullableOptional

Array com os valores de retorno da operação

retValidbooleanOptional

Indica se a operação foi bem-sucedida

Example: true

retDescriptionstringOptional

Descrição do resultado

Example: No error

400

Requisição inválida

application/json

401

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

500

Erro interno do servidor

application/json

post/v4/PayShieldPan/TranslatePinLmkToZpk

POST /v4/PayShieldPan/TranslatePinLmkToZpk HTTP/1.1
Host: apivin.first-tech.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 140

{
  "client_id": 42,
  "keyId": "client-42-key-id-020-ZPK-AES-A3",
  "pin": "MABCDEF0123456789ABCDEF0123456789",
  "pan": "1111222233334444",
  "formatCode": 4
}

{
  "retCode": 0,
  "retValue": "",
  "retMultiValue": [
    "7B263B49A188AB9C30ECF07862F86008"
  ],
  "retValid": true,
  "retDescription": "No error"
}

Traduzir PIN — ZPK (AES) para LMK (AES)

post

Traduz o PIN de criptografia sob uma ZPK (AES) para criptografia sob a LMK (AES). Retorna o PinBlock traduzido em retMultiValue[0].

Quando usado com Variant LMK ou 3DES Key Block LMK, o PIN criptografado sob a LMK sempre usará formato não-ISO.

Authorizations

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

client_idinteger · int64 · min: 1Required

Identificador do cliente

Example: 42

keyIdstringRequired

Alias/identificador da chave ZPK de origem

Example: client-42-key-id-020-ZPK-AES-A3

pinstring · min: 16 · max: 16Required

PinBlock criptografado sob a ZPK (exatamente 16 dígitos)

Example: 7B263B49A188AB9C30ECF07862F86008

panstring · min: 16 · max: 16Required

PAN do cartão (exatamente 16 dígitos)

Example: 1111222233334444

formatCodeinteger · max: 4Required

Código de formato do PinBlock de origem:

0 → formato Thales 01
1 → formato Thales 05
3 → formato Thales 47
4 (padrão) → formato Thales 48

Example: 4

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

retMultiValuestring[] · nullableOptional

Array com os valores de retorno da operação

retValidbooleanOptional

Indica se a operação foi bem-sucedida

Example: true

retDescriptionstringOptional

Descrição do resultado

Example: No error

400

Requisição inválida

application/json

401

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

500

Erro interno do servidor

application/json

post/v4/PayShieldPan/TranslatePinZpkToLmk

POST /v4/PayShieldPan/TranslatePinZpkToLmk HTTP/1.1
Host: apivin.first-tech.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 139

{
  "client_id": 42,
  "keyId": "client-42-key-id-020-ZPK-AES-A3",
  "pin": "7B263B49A188AB9C30ECF07862F86008",
  "pan": "1111222233334444",
  "formatCode": 4
}

{
  "retCode": 0,
  "retValue": "",
  "retMultiValue": [
    "MABCDEF0123456789ABCDEF0123456789"
  ],
  "retValid": true,
  "retDescription": "Ok"
}

Traduzir PIN e PAN combinados

post

Combina a tradução de PAN com a tradução de PIN (LMK para ZPK). Retorna o PinBlock traduzido com o PAN correto em retMultiValue[0].

O PIN do cliente permanece inalterado durante a tradução do PAN.

Quando usando AES Key Block LMK, o PIN criptografado sob a LMK usa o formato Thales 48 (ISO PIN Block format 4).

Authorizations

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

client_idinteger · int64 · min: 1Required

Identificador do cliente

Example: 42

pinstringRequired

PIN criptografado sob a LMK

Example: M1F5A7C1B7B3FC5B15466A9B652A48270

panstringRequired

PAN do cartão

Example: 1111222233334444

keyIdstringRequired

Alias/identificador da chave ZPK de destino

Example: client-4-key-id-253-ZPK-A1

formatCodeinteger · max: 4Required

Código de formato do PinBlock:

0 → formato Thales 01
1 → formato Thales 05
3 → formato Thales 47
4 (padrão) → formato Thales 48

Example: 4

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

retMultiValuestring[] · nullableOptional

Array com os valores de retorno da operação

retValidbooleanOptional

Indica se a operação foi bem-sucedida

Example: true

retDescriptionstringOptional

Descrição do resultado

Example: No error

400

Requisição inválida

application/json

401

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

500

Erro interno do servidor

application/json

post/v4/PayShieldPan/TranslatePinPan

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

{
  "client_id": 42,
  "pin": "M1F5A7C1B7B3FC5B15466A9B652A48270",
  "pan": "1111222233334444",
  "keyId": "client-4-key-id-253-ZPK-A1",
  "formatCode": 4
}

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

Validar PIN com chave do emissor

post

Combina a tradução de PIN (ZPK para LMK) com a validação do PIN. Retorna true em retValid se o PIN for válido. 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 da chave ZPK 3DES usada para criptografar o PIN recebido

Example: client-4-key-id-254-ZPK-3DES-T2

keyIdDbstringRequired

Alias da chave ZPK AES usada para criptografar o PIN armazenado

Example: client-4-key-id-253-ZPK-A1

pinstringRequired

PIN recebido (criptografado sob keyId)

Example: 4B77A8BD4ABCF8F5

pinDbstringRequired

PIN armazenado no banco (criptografado sob keyIdDb)

Example: B07A27355EAA47013E504A956BDBF412

formatCodeinteger · max: 4Required

Código de formato do PIN recebido

Example: 0

formatCodeDbinteger · max: 4Required

Código de formato do PIN armazenado

Example: 4

panstringRequired

PAN do cartão

Example: 1111222233334444

Responses

200

Operação realizada com sucesso

application/json

retCodeintegerOptionalExample: 0

retValuestringOptionalExample: PIN Validated

retMultiValueany · nullableOptional

retValidbooleanOptionalExample: true

retDescriptionstringOptionalExample: OK

400

Requisição inválida

application/json

401

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

500

Erro interno do servidor

application/json

post/v4/PayShieldPan/ValidatePinIssuerKey

POST /v4/PayShieldPan/ValidatePinIssuerKey HTTP/1.1
Host: apivin.first-tech.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 222

{
  "client_id": 42,
  "keyId": "client-4-key-id-254-ZPK-3DES-T2",
  "keyIdDb": "client-4-key-id-253-ZPK-A1",
  "pin": "4B77A8BD4ABCF8F5",
  "pinDb": "B07A27355EAA47013E504A956BDBF412",
  "formatCode": 0,
  "formatCodeDb": 4,
  "pan": "1111222233334444"
}

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

PreviousIntrodução e Fundamentos NextCasos de Uso: Cenários 1 a 3

Last updated 2 months ago