> 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/emv.md).
# EMV
## EMV Validate ARPC 4.x Module
> Returns True or False according to the validation of the ARQC (Request Cryptogram) if it is valid or not, in retValid.
```json
{"openapi":"3.0.3","info":{"title":"PayShield EMV API","version":"4.1.32"},"tags":[{"name":"PayShield EMV","description":"Operações de validação de criptogramas EMV (ARPC/ARQC)"}],"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":{"ArpcInput":{"type":"object","required":["client_id","brand","mode","schemeId","mkacKeyId","pan","panSeqNr","field55EmvTags"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"brand":{"type":"string","enum":["MASTERCARD","VISA","AMEX"],"description":"Bandeira do cartão"},"mode":{"type":"string","description":"Modo de operação do comando EMV:\n- `0`: Validar ARQC\n- `1`: Validar ARQC e gerar ARPC método 1 (ARC)\n- `2`: Gerar ARPC método 1 (ARC) sem validar ARQC\n- `3`: Validar ARQC e gerar ARPC método 2 (CSU)\n- `4`: Gerar ARPC método 2 (CSU) sem validar ARQC\n- `5`: Validar ARQC e gerar ARPC métodos 1 e 2\n- `6`: Gerar ARPC métodos 1 e 2 sem validar ARQC\n- `8`: Validar TC/AAC\n- `9`: Validar TC/AAC e gerar ARPC método 1\n"},"schemeId":{"type":"string","description":"Identificador do esquema EMV:\n- `0`: Visa VIS (CVN 10 ou 17)\n- `1`: Mastercard M/Chip (CVN 10 ou 11)\n- `2`: American Express AEIPS\n- `3`: Mastercard M/Chip com PAN length\n- `5`: Visa VIS com PAN length\n- `6`: JCB\n- `7`: Discover\n- `9`: Visa qVSDC\n- `A`: Mastercard PayPass\n- `B`: Mastercard PayPass com PAN length\n- `C`: Mastercard PayPass com padding flag\n"},"iv_ac":{"type":"string","nullable":true,"description":"IV para derivação de chave de sessão EMV 2000.\nObrigatório apenas para `schemeId` = `0` ou `1`.\n"},"branch_height_params":{"type":"string","nullable":true,"description":"Parâmetros de branch/height para derivação de chave de sessão EMV 2000.\nObrigatório apenas para `schemeId` = `0` ou `1`.\n- `0`: Branch factor 2, Tree Height 16\n- `1`: Branch factor 4, Tree Height 8\n"},"mkacKeyId":{"type":"string","description":"Alias/identificador da chave MKAC no banco de dados"},"pan":{"type":"string","description":"PAN do cartão"},"panSeqNr":{"type":"string","description":"Número de sequência do PAN (PSN) — usar `00` se não disponível"},"field55EmvTags":{"type":"string","description":"Dados EMV da transação em formato TLV hexadecimal (campo 55 da ISO 8583).\nO ARQC é extraído automaticamente da tag `9F26`.\nTags relevantes utilizadas: `9F26` (ARQC), `9F36` (ATC), `9F10` (Issuer Application Data), `8C` (CDOL1).\n"},"arc":{"type":"string","nullable":true,"description":"Authorization Response Code — obrigatório para `mode` = `1`, `2`, `5`, `6` ou `9`.\nValor em Hex (ex: `00` = aprovado, `01` = negado).\n"},"arqc":{"type":"string","nullable":true,"description":"ARQC (Authorization Request Cryptogram) em Hex.\nQuando informado, sobrescreve o valor extraído automaticamente da tag `9F26` do `field55EmvTags`.\nUtilizado principalmente no endpoint `ValidateARQC4x`.\n"},"csu":{"type":"string","nullable":true,"description":"Card Status Update — obrigatório para `mode` = `3`, `4`, `5` ou `6`.\n4 bytes em Hex.\n"}}},"ReturnSingle":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValid":{"type":"boolean","description":"Indica se o ARQC foi validado com sucesso"},"retValue":{"type":"string","nullable":true,"description":"ARPC gerado em Hex (quando aplicável)"},"retDescription":{"type":"string","description":"Descrição do resultado"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `500`: Erro interno\n- `400`: Requisição inválida\n- `155`: Chave não encontrada no banco de dados\n"},"retValid":{"type":"boolean"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retDescription":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldEMV/ValidateARQC4x":{"post":{"tags":["PayShield EMV"],"summary":"EMV Validate ARPC 4.x Module","description":"Returns True or False according to the validation of the ARQC (Request Cryptogram) if it is valid or not, in retValid.\n","operationId":"validateARQC4x","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArpcInput"}}}},"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"},"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"}}}}}}}}}
```
## The ArpcInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield EMV API","version":"4.1.32"},"components":{"schemas":{"ArpcInput":{"type":"object","required":["client_id","brand","mode","schemeId","mkacKeyId","pan","panSeqNr","field55EmvTags"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"brand":{"type":"string","enum":["MASTERCARD","VISA","AMEX"],"description":"Bandeira do cartão"},"mode":{"type":"string","description":"Modo de operação do comando EMV:\n- `0`: Validar ARQC\n- `1`: Validar ARQC e gerar ARPC método 1 (ARC)\n- `2`: Gerar ARPC método 1 (ARC) sem validar ARQC\n- `3`: Validar ARQC e gerar ARPC método 2 (CSU)\n- `4`: Gerar ARPC método 2 (CSU) sem validar ARQC\n- `5`: Validar ARQC e gerar ARPC métodos 1 e 2\n- `6`: Gerar ARPC métodos 1 e 2 sem validar ARQC\n- `8`: Validar TC/AAC\n- `9`: Validar TC/AAC e gerar ARPC método 1\n"},"schemeId":{"type":"string","description":"Identificador do esquema EMV:\n- `0`: Visa VIS (CVN 10 ou 17)\n- `1`: Mastercard M/Chip (CVN 10 ou 11)\n- `2`: American Express AEIPS\n- `3`: Mastercard M/Chip com PAN length\n- `5`: Visa VIS com PAN length\n- `6`: JCB\n- `7`: Discover\n- `9`: Visa qVSDC\n- `A`: Mastercard PayPass\n- `B`: Mastercard PayPass com PAN length\n- `C`: Mastercard PayPass com padding flag\n"},"iv_ac":{"type":"string","nullable":true,"description":"IV para derivação de chave de sessão EMV 2000.\nObrigatório apenas para `schemeId` = `0` ou `1`.\n"},"branch_height_params":{"type":"string","nullable":true,"description":"Parâmetros de branch/height para derivação de chave de sessão EMV 2000.\nObrigatório apenas para `schemeId` = `0` ou `1`.\n- `0`: Branch factor 2, Tree Height 16\n- `1`: Branch factor 4, Tree Height 8\n"},"mkacKeyId":{"type":"string","description":"Alias/identificador da chave MKAC no banco de dados"},"pan":{"type":"string","description":"PAN do cartão"},"panSeqNr":{"type":"string","description":"Número de sequência do PAN (PSN) — usar `00` se não disponível"},"field55EmvTags":{"type":"string","description":"Dados EMV da transação em formato TLV hexadecimal (campo 55 da ISO 8583).\nO ARQC é extraído automaticamente da tag `9F26`.\nTags relevantes utilizadas: `9F26` (ARQC), `9F36` (ATC), `9F10` (Issuer Application Data), `8C` (CDOL1).\n"},"arc":{"type":"string","nullable":true,"description":"Authorization Response Code — obrigatório para `mode` = `1`, `2`, `5`, `6` ou `9`.\nValor em Hex (ex: `00` = aprovado, `01` = negado).\n"},"arqc":{"type":"string","nullable":true,"description":"ARQC (Authorization Request Cryptogram) em Hex.\nQuando informado, sobrescreve o valor extraído automaticamente da tag `9F26` do `field55EmvTags`.\nUtilizado principalmente no endpoint `ValidateARQC4x`.\n"},"csu":{"type":"string","nullable":true,"description":"Card Status Update — obrigatório para `mode` = `3`, `4`, `5` ou `6`.\n4 bytes em Hex.\n"}}}}}}
```
## The ReturnSingle object
```json
{"openapi":"3.0.3","info":{"title":"PayShield EMV API","version":"4.1.32"},"components":{"schemas":{"ReturnSingle":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValid":{"type":"boolean","description":"Indica se o ARQC foi validado com sucesso"},"retValue":{"type":"string","nullable":true,"description":"ARPC gerado em Hex (quando aplicável)"},"retDescription":{"type":"string","description":"Descrição do resultado"}}}}}}
```
## The ReturnError object
```json
{"openapi":"3.0.3","info":{"title":"PayShield EMV API","version":"4.1.32"},"components":{"schemas":{"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `500`: Erro interno\n- `400`: Requisição inválida\n- `155`: Chave não encontrada no banco de dados\n"},"retValid":{"type":"boolean"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"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/hop-api/docs/emv.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.