> For the complete documentation index, see [llms.txt](https://ftcoders.first-tech.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ftcoders.first-tech.com/landing-page/modulo-pan/referencia-api-pan.md).
# 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
> 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\`).
```json
{"openapi":"3.0.3","info":{"title":"PayShield PAN API","version":"4.1.32"},"tags":[{"name":"PIN","description":"Operações de geração, validação e tradução de PIN"}],"servers":[{"url":"https://apivin.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"GeneratePinInput":{"type":"object","required":["client_id","pan","pinLength"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"pan":{"type":"string","minLength":12,"maxLength":19,"description":"PAN do cartão (12 a 19 dígitos)"},"pinLength":{"type":"integer","minimum":4,"maximum":12,"description":"Comprimento do PIN a ser gerado (4 a 12 dígitos)"}}},"ReturnMultiValue":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","nullable":true,"description":"Valor de retorno simples"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com os valores de retorno da operação"},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retDescription":{"type":"string","description":"Descrição do resultado"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `-1`: Erro interno\n- `01`: Falha na verificação do PIN\n- `10`: Erro de paridade na chave ZPK de origem\n- `11`: Erro de paridade na chave ZPK de destino\n- `17`: Tradução de PIN desabilitada\n- `68`: Comando desabilitado\n- `69`: Formato do PinBlock desabilitado\n- `81`: Tamanho do PIN incompatível\n- `88`: Aviso — PinBlock contém PIN de tamanho zero\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDescription":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldPan/GeneratePin":{"post":{"tags":["PIN"],"summary":"Gerar PIN aleatório","description":"Gera um PIN aleatório e retorna o PIN criptografado sob a LMK em `retMultiValue[0]`.\nEm caso de erro, retorna os campos de erro (`retCode` e `retDescription`).\n","operationId":"generatePin","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneratePinInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnMultiValue"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
***
## Gerar PIN com chave do emissor
> 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\`).
```json
{"openapi":"3.0.3","info":{"title":"PayShield PAN API","version":"4.1.32"},"tags":[{"name":"PIN","description":"Operações de geração, validação e tradução de PIN"}],"servers":[{"url":"https://apivin.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"GeneratePinIssuerKeyInput":{"type":"object","required":["client_id","pan","pinLength","keyIdDb"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"pan":{"type":"string","description":"PAN do cartão"},"pinLength":{"type":"integer","minimum":4,"maximum":12,"description":"Comprimento do PIN a ser gerado"},"keyIdDb":{"type":"string","description":"Alias/identificador da chave ZPK do emissor no banco de dados"}}},"ReturnGenericObj":{"type":"object","properties":{"retCode":{"type":"integer"},"retValue":{"type":"string"},"retMultiValue":{"type":"object","nullable":true,"description":"Objeto com os valores de retorno (estrutura varia por operação)"},"retValid":{"type":"boolean"},"retDescription":{"type":"string"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `-1`: Erro interno\n- `01`: Falha na verificação do PIN\n- `10`: Erro de paridade na chave ZPK de origem\n- `11`: Erro de paridade na chave ZPK de destino\n- `17`: Tradução de PIN desabilitada\n- `68`: Comando desabilitado\n- `69`: Formato do PinBlock desabilitado\n- `81`: Tamanho do PIN incompatível\n- `88`: Aviso — PinBlock contém PIN de tamanho zero\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDescription":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldPan/GeneratePinIssuerKey":{"post":{"tags":["PIN"],"summary":"Gerar PIN com chave do emissor","description":"Gera um novo PIN e o criptografa com a chave do emissor (`keyIdDb`).\nRetorna o PIN gerado em `retMultiValue.generatedPin`.\nEm caso de erro, retorna os campos de erro (`retCode` e `retDescription`).\n","operationId":"generatePinIssuerKey","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneratePinIssuerKeyInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnGenericObj"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
***
## PIN Embossing — LMK (AES) para ZPK (3DES)
> 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).
```json
{"openapi":"3.0.3","info":{"title":"PayShield PAN API","version":"4.1.32"},"tags":[{"name":"PIN","description":"Operações de geração, validação e tradução de PIN"}],"servers":[{"url":"https://apivin.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"PinEmbossingInput":{"type":"object","required":["client_id","zpkKeyIdSrc","zpkKeyIdDst","pinBlockSrc","pan","pinBlockFmtDst"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"zpkKeyIdSrc":{"type":"string","description":"Alias da chave de origem AES (LMK)"},"zpkKeyIdDst":{"type":"string","description":"Alias da chave de destino 3DES (ZPK)"},"pinBlockSrc":{"type":"string","minLength":4,"maxLength":33,"description":"PinBlock de origem criptografado sob a chave AES"},"pan":{"type":"string","minLength":16,"maxLength":16,"description":"PAN do cartão (exatamente 16 dígitos)"},"pinBlockFmtDst":{"type":"string","minLength":2,"maxLength":2,"description":"Formato do PinBlock de destino. Valores válidos:\n`01`, `02`, `03`, `04`, `05`, `34`, `35`, `41`, `42`, `47`, `48`\n"}}},"ReturnMultiValue":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","nullable":true,"description":"Valor de retorno simples"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com os valores de retorno da operação"},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retDescription":{"type":"string","description":"Descrição do resultado"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `-1`: Erro interno\n- `01`: Falha na verificação do PIN\n- `10`: Erro de paridade na chave ZPK de origem\n- `11`: Erro de paridade na chave ZPK de destino\n- `17`: Tradução de PIN desabilitada\n- `68`: Comando desabilitado\n- `69`: Formato do PinBlock desabilitado\n- `81`: Tamanho do PIN incompatível\n- `88`: Aviso — PinBlock contém PIN de tamanho zero\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDescription":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldPan/PinEmbossing":{"post":{"tags":["PIN"],"summary":"PIN Embossing — LMK (AES) para ZPK (3DES)","description":"Traduz o PIN de criptografia sob a LMK (AES) para criptografia sob uma ZPK (3DES).\nRetorna o PinBlock traduzido em `retMultiValue[0]`.\n\nChaves de criptografia AES só podem ser usadas com o formato de PinBlock `48` (ISO PIN Block Format 4).\n","operationId":"pinEmbossing","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PinEmbossingInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnMultiValue"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
***
## PIN Internalization — ZPK (3DES) para LMK (AES)
> 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).
```json
{"openapi":"3.0.3","info":{"title":"PayShield PAN API","version":"4.1.32"},"tags":[{"name":"PIN","description":"Operações de geração, validação e tradução de PIN"}],"servers":[{"url":"https://apivin.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"PinInternalizationInput":{"type":"object","required":["client_id","zpkKeyIdSrc","zpkKeyIdDst","pinBlockSrc","pinBlockFmtSrc","pan"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"zpkKeyIdSrc":{"type":"string","description":"Alias da chave de origem 3DES (ZPK)"},"zpkKeyIdDst":{"type":"string","description":"Alias da chave de destino AES (LMK)"},"pinBlockSrc":{"type":"string","minLength":4,"maxLength":33,"description":"PinBlock de origem criptografado sob a chave 3DES"},"pinBlockFmtSrc":{"type":"string","description":"Formato do PinBlock de origem. Valores válidos:\n`01`, `02`, `03`, `04`, `05`, `34`, `35`, `41`, `42`, `47`\n(formato `48` não é suportado para chaves 3DES)\n"},"pan":{"type":"string","minLength":16,"maxLength":16,"description":"PAN do cartão (exatamente 16 dígitos)"}}},"ReturnMultiValue":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","nullable":true,"description":"Valor de retorno simples"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com os valores de retorno da operação"},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retDescription":{"type":"string","description":"Descrição do resultado"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `-1`: Erro interno\n- `01`: Falha na verificação do PIN\n- `10`: Erro de paridade na chave ZPK de origem\n- `11`: Erro de paridade na chave ZPK de destino\n- `17`: Tradução de PIN desabilitada\n- `68`: Comando desabilitado\n- `69`: Formato do PinBlock desabilitado\n- `81`: Tamanho do PIN incompatível\n- `88`: Aviso — PinBlock contém PIN de tamanho zero\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDescription":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldPan/PinInternalization":{"post":{"tags":["PIN"],"summary":"PIN Internalization — ZPK (3DES) para LMK (AES)","description":"Traduz o PIN de criptografia sob uma ZPK (3DES) para criptografia sob a LMK (AES).\nRetorna o PinBlock traduzido em `retMultiValue[0]`.\n\nChaves 3DES não podem ser usadas com o formato de PinBlock `48` (ISO PIN Block Format 4).\n","operationId":"pinInternalization","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PinInternalizationInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnMultiValue"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
## Traduzir PAN
> 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).
```json
{"openapi":"3.0.3","info":{"title":"PayShield PAN API","version":"4.1.32"},"tags":[{"name":"PAN","description":"Operações de tradução de PAN"}],"servers":[{"url":"https://apivin.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"TranslatePanInput":{"type":"object","required":["client_id","pin","oldPan","newPan"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"pin":{"type":"string","maxLength":33,"description":"PIN criptografado sob a LMK"},"oldPan":{"type":"string","minLength":12,"maxLength":19,"description":"PAN antigo do cartão (12 a 19 dígitos)"},"newPan":{"type":"string","minLength":12,"maxLength":19,"description":"Novo PAN do cartão (12 a 19 dígitos)"}}},"ReturnMultiValue":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","nullable":true,"description":"Valor de retorno simples"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com os valores de retorno da operação"},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retDescription":{"type":"string","description":"Descrição do resultado"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `-1`: Erro interno\n- `01`: Falha na verificação do PIN\n- `10`: Erro de paridade na chave ZPK de origem\n- `11`: Erro de paridade na chave ZPK de destino\n- `17`: Tradução de PIN desabilitada\n- `68`: Comando desabilitado\n- `69`: Formato do PinBlock desabilitado\n- `81`: Tamanho do PIN incompatível\n- `88`: Aviso — PinBlock contém PIN de tamanho zero\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDescription":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldPan/TranslatePan":{"post":{"tags":["PAN"],"summary":"Traduzir PAN","description":"Traduz o PIN criptografado sob a LMK de um PAN antigo para um PAN novo.\nO PIN do cliente permanece inalterado.\nRetorna o PIN re-criptografado com o novo PAN em `retMultiValue[0]`.\n\nQuando usando AES Key Block LMK, o PIN criptografado sob a LMK usa o formato Thales `48` (ISO PIN Block format 4).\n","operationId":"translatePan","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslatePanInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnMultiValue"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
***
## Traduzir PIN — LMK (AES) para ZPK (AES)
> 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.
```json
{"openapi":"3.0.3","info":{"title":"PayShield PAN API","version":"4.1.32"},"tags":[{"name":"PIN","description":"Operações de geração, validação e tradução de PIN"}],"servers":[{"url":"https://apivin.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"TranslatePinLmkToZpkInput":{"type":"object","required":["client_id","keyId","pin","pan","formatCode"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave ZPK de destino"},"pin":{"type":"string","maxLength":33,"description":"PIN criptografado sob a LMK"},"pan":{"type":"string","description":"PAN do cartão"},"formatCode":{"type":"integer","minimum":0,"maximum":4,"description":"Código de formato do PinBlock de destino:\n- `0` → formato Thales `01`\n- `1` → formato Thales `05`\n- `3` → formato Thales `47`\n- `4` (padrão) → formato Thales `48`\n"}}},"ReturnMultiValue":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","nullable":true,"description":"Valor de retorno simples"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com os valores de retorno da operação"},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retDescription":{"type":"string","description":"Descrição do resultado"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `-1`: Erro interno\n- `01`: Falha na verificação do PIN\n- `10`: Erro de paridade na chave ZPK de origem\n- `11`: Erro de paridade na chave ZPK de destino\n- `17`: Tradução de PIN desabilitada\n- `68`: Comando desabilitado\n- `69`: Formato do PinBlock desabilitado\n- `81`: Tamanho do PIN incompatível\n- `88`: Aviso — PinBlock contém PIN de tamanho zero\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDescription":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldPan/TranslatePinLmkToZpk":{"post":{"tags":["PIN"],"summary":"Traduzir PIN — LMK (AES) para ZPK (AES)","description":"Traduz o PIN de criptografia sob a LMK (AES) para criptografia sob uma ZPK (AES).\nRetorna o PinBlock traduzido em `retMultiValue[0]`.\n\nQuando usado com Variant LMK ou 3DES Key Block LMK, o PIN criptografado sob a LMK sempre usará formato não-ISO.\n","operationId":"translatePinLmkToZpk","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslatePinLmkToZpkInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnMultiValue"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
***
## Traduzir PIN — ZPK (AES) para LMK (AES)
> 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.
```json
{"openapi":"3.0.3","info":{"title":"PayShield PAN API","version":"4.1.32"},"tags":[{"name":"PIN","description":"Operações de geração, validação e tradução de PIN"}],"servers":[{"url":"https://apivin.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"TranslatePinZpkToLmkInput":{"type":"object","required":["client_id","keyId","pin","pan","formatCode"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave ZPK de origem"},"pin":{"type":"string","minLength":16,"maxLength":16,"description":"PinBlock criptografado sob a ZPK (exatamente 16 dígitos)"},"pan":{"type":"string","minLength":16,"maxLength":16,"description":"PAN do cartão (exatamente 16 dígitos)"},"formatCode":{"type":"integer","minimum":0,"maximum":4,"description":"Código de formato do PinBlock de origem:\n- `0` → formato Thales `01`\n- `1` → formato Thales `05`\n- `3` → formato Thales `47`\n- `4` (padrão) → formato Thales `48`\n"}}},"ReturnMultiValue":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","nullable":true,"description":"Valor de retorno simples"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com os valores de retorno da operação"},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retDescription":{"type":"string","description":"Descrição do resultado"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `-1`: Erro interno\n- `01`: Falha na verificação do PIN\n- `10`: Erro de paridade na chave ZPK de origem\n- `11`: Erro de paridade na chave ZPK de destino\n- `17`: Tradução de PIN desabilitada\n- `68`: Comando desabilitado\n- `69`: Formato do PinBlock desabilitado\n- `81`: Tamanho do PIN incompatível\n- `88`: Aviso — PinBlock contém PIN de tamanho zero\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDescription":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldPan/TranslatePinZpkToLmk":{"post":{"tags":["PIN"],"summary":"Traduzir PIN — ZPK (AES) para LMK (AES)","description":"Traduz o PIN de criptografia sob uma ZPK (AES) para criptografia sob a LMK (AES).\nRetorna o PinBlock traduzido em `retMultiValue[0]`.\n\nQuando usado com Variant LMK ou 3DES Key Block LMK, o PIN criptografado sob a LMK sempre usará formato não-ISO.\n","operationId":"translatePinZpkToLmk","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslatePinZpkToLmkInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnMultiValue"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
***
## Traduzir PIN e PAN combinados
> 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).
```json
{"openapi":"3.0.3","info":{"title":"PayShield PAN API","version":"4.1.32"},"tags":[{"name":"PIN","description":"Operações de geração, validação e tradução de PIN"}],"servers":[{"url":"https://apivin.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"TranslatePinPanInput":{"type":"object","required":["client_id","pin","pan","keyId","formatCode"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"pin":{"type":"string","description":"PIN criptografado sob a LMK"},"pan":{"type":"string","description":"PAN do cartão"},"keyId":{"type":"string","description":"Alias/identificador da chave ZPK de destino"},"formatCode":{"type":"integer","minimum":0,"maximum":4,"description":"Código de formato do PinBlock:\n- `0` → formato Thales `01`\n- `1` → formato Thales `05`\n- `3` → formato Thales `47`\n- `4` (padrão) → formato Thales `48`\n"}}},"ReturnMultiValue":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","nullable":true,"description":"Valor de retorno simples"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com os valores de retorno da operação"},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retDescription":{"type":"string","description":"Descrição do resultado"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `-1`: Erro interno\n- `01`: Falha na verificação do PIN\n- `10`: Erro de paridade na chave ZPK de origem\n- `11`: Erro de paridade na chave ZPK de destino\n- `17`: Tradução de PIN desabilitada\n- `68`: Comando desabilitado\n- `69`: Formato do PinBlock desabilitado\n- `81`: Tamanho do PIN incompatível\n- `88`: Aviso — PinBlock contém PIN de tamanho zero\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDescription":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldPan/TranslatePinPan":{"post":{"tags":["PIN"],"summary":"Traduzir PIN e PAN combinados","description":"Combina a tradução de PAN com a tradução de PIN (LMK para ZPK).\nRetorna o PinBlock traduzido com o PAN correto em `retMultiValue[0]`.\n\nO PIN do cliente permanece inalterado durante a tradução do PAN.\n\nQuando usando AES Key Block LMK, o PIN criptografado sob a LMK usa o formato Thales `48` (ISO PIN Block format 4).\n","operationId":"translatePinPan","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslatePinPanInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnMultiValue"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
***
## Validar PIN com chave do emissor
> 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\`).
```json
{"openapi":"3.0.3","info":{"title":"PayShield PAN API","version":"4.1.32"},"tags":[{"name":"PIN","description":"Operações de geração, validação e tradução de PIN"}],"servers":[{"url":"https://apivin.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"ValidatePinIssuerKeyInput":{"type":"object","required":["client_id","keyId","keyIdDb","pin","pinDb","formatCode","formatCodeDb","pan"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias da chave ZPK 3DES usada para criptografar o PIN recebido"},"keyIdDb":{"type":"string","description":"Alias da chave ZPK AES usada para criptografar o PIN armazenado"},"pin":{"type":"string","description":"PIN recebido (criptografado sob `keyId`)"},"pinDb":{"type":"string","description":"PIN armazenado no banco (criptografado sob `keyIdDb`)"},"formatCode":{"type":"integer","minimum":0,"maximum":4,"description":"Código de formato do PIN recebido"},"formatCodeDb":{"type":"integer","minimum":0,"maximum":4,"description":"Código de formato do PIN armazenado"},"pan":{"type":"string","description":"PAN do cartão"}}},"ReturnSingle":{"type":"object","properties":{"retCode":{"type":"integer"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDescription":{"type":"string"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `-1`: Erro interno\n- `01`: Falha na verificação do PIN\n- `10`: Erro de paridade na chave ZPK de origem\n- `11`: Erro de paridade na chave ZPK de destino\n- `17`: Tradução de PIN desabilitada\n- `68`: Comando desabilitado\n- `69`: Formato do PinBlock desabilitado\n- `81`: Tamanho do PIN incompatível\n- `88`: Aviso — PinBlock contém PIN de tamanho zero\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDescription":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldPan/ValidatePinIssuerKey":{"post":{"tags":["PIN"],"summary":"Validar PIN com chave do emissor","description":"Combina a tradução de PIN (ZPK para LMK) com a validação do PIN.\nRetorna `true` em `retValid` se o PIN for válido.\nEm caso de erro, retorna os campos de erro (`retCode` e `retDescription`).\n","operationId":"validatePinIssuerKey","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidatePinIssuerKeyInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnSingle"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
***
## The GeneratePinInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield PAN API","version":"4.1.32"},"components":{"schemas":{"GeneratePinInput":{"type":"object","required":["client_id","pan","pinLength"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"pan":{"type":"string","minLength":12,"maxLength":19,"description":"PAN do cartão (12 a 19 dígitos)"},"pinLength":{"type":"integer","minimum":4,"maximum":12,"description":"Comprimento do PIN a ser gerado (4 a 12 dígitos)"}}}}}}
```
## The GeneratePinIssuerKeyInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield PAN API","version":"4.1.32"},"components":{"schemas":{"GeneratePinIssuerKeyInput":{"type":"object","required":["client_id","pan","pinLength","keyIdDb"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"pan":{"type":"string","description":"PAN do cartão"},"pinLength":{"type":"integer","minimum":4,"maximum":12,"description":"Comprimento do PIN a ser gerado"},"keyIdDb":{"type":"string","description":"Alias/identificador da chave ZPK do emissor no banco de dados"}}}}}}
```
## The PinEmbossingInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield PAN API","version":"4.1.32"},"components":{"schemas":{"PinEmbossingInput":{"type":"object","required":["client_id","zpkKeyIdSrc","zpkKeyIdDst","pinBlockSrc","pan","pinBlockFmtDst"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"zpkKeyIdSrc":{"type":"string","description":"Alias da chave de origem AES (LMK)"},"zpkKeyIdDst":{"type":"string","description":"Alias da chave de destino 3DES (ZPK)"},"pinBlockSrc":{"type":"string","minLength":4,"maxLength":33,"description":"PinBlock de origem criptografado sob a chave AES"},"pan":{"type":"string","minLength":16,"maxLength":16,"description":"PAN do cartão (exatamente 16 dígitos)"},"pinBlockFmtDst":{"type":"string","minLength":2,"maxLength":2,"description":"Formato do PinBlock de destino. Valores válidos:\n`01`, `02`, `03`, `04`, `05`, `34`, `35`, `41`, `42`, `47`, `48`\n"}}}}}}
```
## The PinInternalizationInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield PAN API","version":"4.1.32"},"components":{"schemas":{"PinInternalizationInput":{"type":"object","required":["client_id","zpkKeyIdSrc","zpkKeyIdDst","pinBlockSrc","pinBlockFmtSrc","pan"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"zpkKeyIdSrc":{"type":"string","description":"Alias da chave de origem 3DES (ZPK)"},"zpkKeyIdDst":{"type":"string","description":"Alias da chave de destino AES (LMK)"},"pinBlockSrc":{"type":"string","minLength":4,"maxLength":33,"description":"PinBlock de origem criptografado sob a chave 3DES"},"pinBlockFmtSrc":{"type":"string","description":"Formato do PinBlock de origem. Valores válidos:\n`01`, `02`, `03`, `04`, `05`, `34`, `35`, `41`, `42`, `47`\n(formato `48` não é suportado para chaves 3DES)\n"},"pan":{"type":"string","minLength":16,"maxLength":16,"description":"PAN do cartão (exatamente 16 dígitos)"}}}}}}
```
## The TranslatePanInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield PAN API","version":"4.1.32"},"components":{"schemas":{"TranslatePanInput":{"type":"object","required":["client_id","pin","oldPan","newPan"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"pin":{"type":"string","maxLength":33,"description":"PIN criptografado sob a LMK"},"oldPan":{"type":"string","minLength":12,"maxLength":19,"description":"PAN antigo do cartão (12 a 19 dígitos)"},"newPan":{"type":"string","minLength":12,"maxLength":19,"description":"Novo PAN do cartão (12 a 19 dígitos)"}}}}}}
```
## The TranslatePinLmkToZpkInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield PAN API","version":"4.1.32"},"components":{"schemas":{"TranslatePinLmkToZpkInput":{"type":"object","required":["client_id","keyId","pin","pan","formatCode"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave ZPK de destino"},"pin":{"type":"string","maxLength":33,"description":"PIN criptografado sob a LMK"},"pan":{"type":"string","description":"PAN do cartão"},"formatCode":{"type":"integer","minimum":0,"maximum":4,"description":"Código de formato do PinBlock de destino:\n- `0` → formato Thales `01`\n- `1` → formato Thales `05`\n- `3` → formato Thales `47`\n- `4` (padrão) → formato Thales `48`\n"}}}}}}
```
## The TranslatePinZpkToLmkInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield PAN API","version":"4.1.32"},"components":{"schemas":{"TranslatePinZpkToLmkInput":{"type":"object","required":["client_id","keyId","pin","pan","formatCode"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave ZPK de origem"},"pin":{"type":"string","minLength":16,"maxLength":16,"description":"PinBlock criptografado sob a ZPK (exatamente 16 dígitos)"},"pan":{"type":"string","minLength":16,"maxLength":16,"description":"PAN do cartão (exatamente 16 dígitos)"},"formatCode":{"type":"integer","minimum":0,"maximum":4,"description":"Código de formato do PinBlock de origem:\n- `0` → formato Thales `01`\n- `1` → formato Thales `05`\n- `3` → formato Thales `47`\n- `4` (padrão) → formato Thales `48`\n"}}}}}}
```
## The TranslatePinPanInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield PAN API","version":"4.1.32"},"components":{"schemas":{"TranslatePinPanInput":{"type":"object","required":["client_id","pin","pan","keyId","formatCode"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"pin":{"type":"string","description":"PIN criptografado sob a LMK"},"pan":{"type":"string","description":"PAN do cartão"},"keyId":{"type":"string","description":"Alias/identificador da chave ZPK de destino"},"formatCode":{"type":"integer","minimum":0,"maximum":4,"description":"Código de formato do PinBlock:\n- `0` → formato Thales `01`\n- `1` → formato Thales `05`\n- `3` → formato Thales `47`\n- `4` (padrão) → formato Thales `48`\n"}}}}}}
```
## The ValidatePinIssuerKeyInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield PAN API","version":"4.1.32"},"components":{"schemas":{"ValidatePinIssuerKeyInput":{"type":"object","required":["client_id","keyId","keyIdDb","pin","pinDb","formatCode","formatCodeDb","pan"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias da chave ZPK 3DES usada para criptografar o PIN recebido"},"keyIdDb":{"type":"string","description":"Alias da chave ZPK AES usada para criptografar o PIN armazenado"},"pin":{"type":"string","description":"PIN recebido (criptografado sob `keyId`)"},"pinDb":{"type":"string","description":"PIN armazenado no banco (criptografado sob `keyIdDb`)"},"formatCode":{"type":"integer","minimum":0,"maximum":4,"description":"Código de formato do PIN recebido"},"formatCodeDb":{"type":"integer","minimum":0,"maximum":4,"description":"Código de formato do PIN armazenado"},"pan":{"type":"string","description":"PAN do cartão"}}}}}}
```
## The ReturnMultiValue object
```json
{"openapi":"3.0.3","info":{"title":"PayShield PAN API","version":"4.1.32"},"components":{"schemas":{"ReturnMultiValue":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","nullable":true,"description":"Valor de retorno simples"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com os valores de retorno da operação"},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retDescription":{"type":"string","description":"Descrição do resultado"}}}}}}
```
## The ReturnSingle object
```json
{"openapi":"3.0.3","info":{"title":"PayShield PAN API","version":"4.1.32"},"components":{"schemas":{"ReturnSingle":{"type":"object","properties":{"retCode":{"type":"integer"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDescription":{"type":"string"}}}}}}
```
## The ReturnGenericObj object
```json
{"openapi":"3.0.3","info":{"title":"PayShield PAN API","version":"4.1.32"},"components":{"schemas":{"ReturnGenericObj":{"type":"object","properties":{"retCode":{"type":"integer"},"retValue":{"type":"string"},"retMultiValue":{"type":"object","nullable":true,"description":"Objeto com os valores de retorno (estrutura varia por operação)"},"retValid":{"type":"boolean"},"retDescription":{"type":"string"}}}}}}
```
## The ReturnError object
```json
{"openapi":"3.0.3","info":{"title":"PayShield PAN API","version":"4.1.32"},"components":{"schemas":{"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `-1`: Erro interno\n- `01`: Falha na verificação do PIN\n- `10`: Erro de paridade na chave ZPK de origem\n- `11`: Erro de paridade na chave ZPK de destino\n- `17`: Tradução de PIN desabilitada\n- `68`: Comando desabilitado\n- `69`: Formato do PinBlock desabilitado\n- `81`: Tamanho do PIN incompatível\n- `88`: Aviso — PinBlock contém PIN de tamanho zero\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDescription":{"type":"string","description":"Descrição do erro"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://ftcoders.first-tech.com/landing-page/modulo-pan/referencia-api-pan.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.