> 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-pin/referencia-api-pin.md).
# Referência API - PIN
## Validar PIN
> 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\`).
```json
{"openapi":"3.0.3","info":{"title":"PayShield PIN API","version":"4.1.32"},"tags":[{"name":"PIN","description":"Operações de tradução e validaçã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":{"ValidatePinInput":{"type":"object","required":["client_id","keyId","hPibBlock","pibBlockFmt","pan"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave TPK ou ZPK no banco de dados"},"hPibBlock":{"type":"string","description":"PinBlock em formato Hexadecimal"},"pibBlockFmt":{"type":"string","description":"Formato do PinBlock. Valores válidos:\n`01`, `02`, `03`, `04`, `05`, `34`, `35`, `41`, `42`, `47`, `48`\n"},"hPinHost":{"type":"string","nullable":true,"description":"PIN Host em formato Hexadecimal (usado para validação contra PIN armazenado)"},"pan":{"type":"string","description":"PAN do cartão (16 a 19 dígitos)"}}},"ReturnSingle":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","description":"Valor de retorno simples"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retDesc":{"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 TPK 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- `88`: Aviso — PinBlock contém PIN de tamanho zero\n- `137`: Malformação da requisição\n- `155`: Chave não encontrada no banco de dados\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDesc":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldPin/ValidatePin":{"post":{"tags":["PIN"],"summary":"Validar PIN","description":"Valida o PIN do portador do cartão comparando o PinBlock recebido com o PIN armazenado no HSM.\nRetorna `true` em `retValid` se o PIN for válido, `false` caso contrário.\nEm caso de erro, retorna os campos de erro (`retCode` e `retDescription`).\n","operationId":"validatePin","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidatePinInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnSingle"}}}},"400":{"description":"Requisição inválida — campo obrigatório ausente ou formato incorreto","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"404":{"description":"Chave não encontrada no banco de dados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
***
## Traduzir PIN
> 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\`).
```json
{"openapi":"3.0.3","info":{"title":"PayShield PIN API","version":"4.1.32"},"tags":[{"name":"PIN","description":"Operações de tradução e validaçã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":{"TranslatePinInput":{"type":"object","required":["client_id","keyIdSrc","hPibBlockSrc","pibBlockFmtSrc","keyIdDst","pibBlockFmtDst","pan"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyIdSrc":{"type":"string","description":"Alias/identificador da chave de origem (TPK, ZPK ou BDK)"},"hPibBlockSrc":{"type":"string","description":"PinBlock de origem em formato alfanumérico (a-z, A-Z, 0-9)"},"pibBlockFmtSrc":{"type":"string","description":"Formato do PinBlock de origem. Valores válidos:\n`01`, `02`, `03`, `04`, `05`, `34`, `35`, `41`, `42`, `47`, `48`\n"},"hPinHost":{"type":"string","nullable":true,"description":"PIN Host em formato Hexadecimal (opcional)"},"keyIdDst":{"type":"string","description":"Alias/identificador da chave de destino (TPK, ZPK ou BDK)"},"pibBlockFmtDst":{"type":"string","description":"Formato do PinBlock de destino. Valores válidos:\n`01`, `02`, `03`, `04`, `05`, `34`, `35`, `41`, `42`, `47`, `48`\n"},"pan":{"type":"string","description":"PAN do cartão de origem (16 a 19 dígitos)"},"ksn_desc":{"type":"string","nullable":true,"description":"Descritor KSN da chave de origem — necessário apenas se `keyIdSrc` for do tipo BDK (DUKPT)"},"ksn":{"type":"string","nullable":true,"description":"KSN da chave de origem — necessário apenas se `keyIdSrc` for do tipo BDK (DUKPT)"},"pan_dst":{"type":"string","nullable":true,"description":"PAN do cartão de destino (16 a 19 dígitos) — necessário quando o PAN de destino difere do de origem"},"ksn_desc_dst":{"type":"string","nullable":true,"description":"Descritor KSN da chave de destino — necessário apenas se `keyIdDst` for do tipo BDK (DUKPT)"},"ksn_dst":{"type":"string","nullable":true,"description":"KSN da chave de destino — necessário apenas se `keyIdDst` for do tipo BDK (DUKPT)"}}},"ReturnMultiValue":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","description":"Valor de retorno simples (geralmente vazio em sucesso)"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com os valores de retorno da operação TranslatePin:\n- `[0]` = formato do PinBlock de destino\n- `[1]` = PinBlock traduzido (sob a chave de destino)\n- `[2]` = formato do PinBlock de origem\n"},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retDesc":{"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 TPK 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- `88`: Aviso — PinBlock contém PIN de tamanho zero\n- `137`: Malformação da requisição\n- `155`: Chave não encontrada no banco de dados\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDesc":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldPin/TranslatePin":{"post":{"tags":["PIN"],"summary":"Traduzir PIN","description":"Traduz um PinBlock de uma chave de origem (`keyIdSrc`) para uma chave de destino (`keyIdDst`).\nSuporta chaves do tipo TPK, ZPK e BDK (DUKPT).\n\nRetorna em `retMultiValue`:\n- `retMultiValue[0]` = formato do PinBlock de destino\n- `retMultiValue[1]` = PinBlock traduzido (sob a chave de destino)\n- `retMultiValue[2]` = formato do PinBlock de origem\n\nEm caso de erro, retorna os campos de erro (`retCode` e `retDescription`).\n","operationId":"translatePin","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslatePinInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnMultiValue"}}}},"400":{"description":"Requisição inválida — campo obrigatório ausente ou formato incorreto","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"404":{"description":"Chave não encontrada no banco de dados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
---
# 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-pin/referencia-api-pin.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.