> 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/hop-api/docs/pan.md).
# PAN
## PayShield Pan Service
> Generate a Random PIN\
> Returns the new PIN encrypted under the LMK in retMultiValue\[0] with retCode 0 and retDescription Ok. In case of error returns the Error fields (retCode and 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://api-hext.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"},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retValue":{"type":"string","nullable":true,"description":"Valor de retorno simples"},"retDescription":{"type":"string","description":"Descrição do resultado"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com os valores de retorno da operação"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `500`: Erro interno do servidor\n- `400`: Requisição inválida\n- `155`: Chave não encontrada no banco de dados\n"},"retValid":{"type":"boolean"},"retValue":{"type":"string","nullable":true},"retDescription":{"type":"string","description":"Descrição do erro"},"retMultiValue":{"nullable":true}}}}},"paths":{"/v4/PayShieldPan/GeneratePin":{"post":{"tags":["PIN"],"summary":"PayShield Pan Service","description":"Generate a Random PIN\nReturns the new PIN encrypted under the LMK in retMultiValue[0] with retCode 0 and retDescription Ok. In case of error returns the Error fields (retCode and 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"}}}}}}}}}
```
## Translate Pan
> Returns the account number for a PIN encrypted under LMK 02-03 from an old account number to a new account number in retMultiValue\[0] with retCode 0 and retDescription OK. In case of error, it returns details in the Error fields (retCode and RetDescription).\
> \
> The customer PIN itself remains unchanged.\
> \
> When using an AES Key Block LMK, the LMK-encrypted PIN is the result of encrypting the PIN under the LMK using Thales PIN Block format 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://api-hext.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"},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retValue":{"type":"string","nullable":true,"description":"Valor de retorno simples"},"retDescription":{"type":"string","description":"Descrição do resultado"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com os valores de retorno da operação"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `500`: Erro interno do servidor\n- `400`: Requisição inválida\n- `155`: Chave não encontrada no banco de dados\n"},"retValid":{"type":"boolean"},"retValue":{"type":"string","nullable":true},"retDescription":{"type":"string","description":"Descrição do erro"},"retMultiValue":{"nullable":true}}}}},"paths":{"/v4/PayShieldPan/TranslatePan":{"post":{"tags":["PAN"],"summary":"Translate Pan","description":"Returns the account number for a PIN encrypted under LMK 02-03 from an old account number to a new account number in retMultiValue[0] with retCode 0 and retDescription OK. In case of error, it returns details in the Error fields (retCode and RetDescription).\n\nThe customer PIN itself remains unchanged.\n\nWhen using an AES Key Block LMK, the LMK-encrypted PIN is the result of encrypting the PIN under the LMK using Thales PIN Block format 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"}}}}}}}}}
```
## Translate PIN LMK (AES) To ZPK (AES)
> Translate PIN LMK (AES) To ZPK (AES)\
> \
> Returns the translated PIN from encryption under the LMK (AES) to encryption under a ZPK (AES) in retMultiValue\[0] with retCode 0 and retDescription OK. In case of error, it returns details in the Error fields (retCode and RetDescription)\
> \
> When used with a Variant LMK or 3DES Key Block LMK, the PIN encrypted under the LMK will always be using a non-ISO format
```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://api-hext.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"},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retValue":{"type":"string","nullable":true,"description":"Valor de retorno simples"},"retDescription":{"type":"string","description":"Descrição do resultado"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com os valores de retorno da operação"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `500`: Erro interno do servidor\n- `400`: Requisição inválida\n- `155`: Chave não encontrada no banco de dados\n"},"retValid":{"type":"boolean"},"retValue":{"type":"string","nullable":true},"retDescription":{"type":"string","description":"Descrição do erro"},"retMultiValue":{"nullable":true}}}}},"paths":{"/v4/PayShieldPan/TranslatePinLmkToZpk":{"post":{"tags":["PIN"],"summary":"Translate PIN LMK (AES) To ZPK (AES)","description":"Translate PIN LMK (AES) To ZPK (AES)\n\nReturns the translated PIN from encryption under the LMK (AES) to encryption under a ZPK (AES) in retMultiValue[0] with retCode 0 and retDescription OK. In case of error, it returns details in the Error fields (retCode and RetDescription)\n\nWhen used with a Variant LMK or 3DES Key Block LMK, the PIN encrypted under the LMK will always be using a non-ISO format\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"}}}}}}}}}
```
## Translate PIN ZPK (AES) to LMK (AES)
> Returns the translated PIN from encryption under the ZPK (AES) to encryption under a LMK (AES) in retMultiValue\[0] with retCode 0 and retDescription Ok. In case of error, it returns details in the Error fields (retCode and RetDescription)\
> \
> When used with a Variant LMK or 3DES Key Block LMK, the PIN encrypted under the LMK will always be using a non-ISO format
```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://api-hext.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"},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retValue":{"type":"string","nullable":true,"description":"Valor de retorno simples"},"retDescription":{"type":"string","description":"Descrição do resultado"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com os valores de retorno da operação"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `500`: Erro interno do servidor\n- `400`: Requisição inválida\n- `155`: Chave não encontrada no banco de dados\n"},"retValid":{"type":"boolean"},"retValue":{"type":"string","nullable":true},"retDescription":{"type":"string","description":"Descrição do erro"},"retMultiValue":{"nullable":true}}}}},"paths":{"/v4/PayShieldPan/TranslatePinZpkToLmk":{"post":{"tags":["PIN"],"summary":"Translate PIN ZPK (AES) to LMK (AES)","description":"Returns the translated PIN from encryption under the ZPK (AES) to encryption under a LMK (AES) in retMultiValue[0] with retCode 0 and retDescription Ok. In case of error, it returns details in the Error fields (retCode and RetDescription)\n\nWhen used with a Variant LMK or 3DES Key Block LMK, the PIN encrypted under the LMK will always be using a non-ISO format\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"}}}}}}}}}
```
## 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 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 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"},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retValue":{"type":"string","nullable":true,"description":"Valor de retorno simples"},"retDescription":{"type":"string","description":"Descrição do resultado"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com os valores de retorno da operação"}}}}}}
```
## 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- `500`: Erro interno do servidor\n- `400`: Requisição inválida\n- `155`: Chave não encontrada no banco de dados\n"},"retValid":{"type":"boolean"},"retValue":{"type":"string","nullable":true},"retDescription":{"type":"string","description":"Descrição do erro"},"retMultiValue":{"nullable":true}}}}}}
```
---
# 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/hop-api/docs/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.