> 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-emv/referencia-da-api-emv.md). # Referência da API - EMV Esta secção apresenta a especificação técnica completa para o consumo dos endpoints do módulo EMV da Hop V4. ## Autenticação e Base URL Todos os endpoints do módulo EMV da Hop V4 exigem um token Bearer obtido via OAuth2 (`grant_type: client_credentials`). O token é transportado no cabeçalho `Authorization` em toda a requisição. ### Configurações de Conexão:
ParâmetroValor
Base URL (API)https://apivin.first-tech.net [A confirmar host definitivo de PRD/HML]
Endpoint de autenticaçãohttps://auth.first-tech.net/oauth/token
grant_typeclient_credentials
audiencehttps://auth-jwt-authorize-prd-first-tech
token_typeBearer
Tempo de vida (padrão)[A confirmar TTL do token com a equipa técnica]
### Cabeçalhos Obrigatórios (`Headers`): ```http HTTP Authorization: Bearer Content-Type: application/json Accept: */* ``` {% hint style="info" %} #### Estratégia de Renovação de Token: Recomenda-se renovar o token antes da expiração, mantendo um *cache* no lado do cliente. Evite solicitar um novo token a cada chamada EMV, pois isso adiciona latência desnecessária e onera o serviço de autenticação . Em caso de resposta HTTP `401`, descarte o token em *cache*, solicite um novo e reenvie a requisição. {% endhint %} ### POST /ValidateARQC4x ## Validar ARQC (Request Cryptogram) > Valida o ARQC (Authorization Request Cryptogram) recebido no campo 55 da transação EMV.\ > Retorna \`true\` em \`retValid\` se o ARQC for válido, \`false\` caso contrário.\ > Retorna o ARPC gerado em \`retValue\` em formato Hex.\ > \ > O campo \`field55EmvTags\` deve conter os dados EMV da transação em formato TLV hexadecimal.\ > O ARQC é extraído automaticamente da tag \`9F26\` do campo 55.\ > \ > Em caso de erro, retorna os campos de erro (\`retCode\` e \`retDesc\`).
```json {"openapi":"3.0.3","info":{"title":"PayShield EMV API","version":"4.1.32"},"tags":[{"name":"EMV","description":"Operações de geração e validação de criptogramas EMV (ARPC/ARQC)"}],"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":{"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"},"retValue":{"type":"string","nullable":true,"description":"ARPC gerado em Hex (quando aplicável)"},"retValid":{"type":"boolean","description":"Indica se o ARQC foi validado com sucesso"},"retDescription":{"type":"string"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `01`: Falha na verificação do ARQC/TC/AAC/MPVV\n- `03`: Padding Flag inválido\n- `04`: Mode Flag não reconhecido\n- `05`: Scheme ID não reconhecido\n- `06`: Valor YHHHHCC inválido\n- `10`: Erro de paridade na chave MK\n- `52`: Branch/Height inválido\n- `68`: Comando desabilitado\n- `F1`: Método de derivação de chave inválido\n- `F2`: Método de validação ARQC inválido\n- `F3`: Algoritmo da chave MK-AC não é AES\n- `F5`: Método de chave de sessão inválido\n- `F8`: Método de geração de chave OTPK inválido\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDesc":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldEMV/ValidateARQC4x":{"post":{"tags":["EMV"],"summary":"Validar ARQC (Request Cryptogram)","description":"Valida o ARQC (Authorization Request Cryptogram) recebido no campo 55 da transação EMV.\nRetorna `true` em `retValid` se o ARQC for válido, `false` caso contrário.\nRetorna o ARPC gerado em `retValue` em formato Hex.\n\nO campo `field55EmvTags` deve conter os dados EMV da transação em formato TLV hexadecimal.\nO ARQC é extraído automaticamente da tag `9F26` do campo 55.\n\nEm caso de erro, retorna os campos de erro (`retCode` e `retDesc`).\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"}}}}}}}}} ``` ### POST /GenerateARPC4x ## Gerar ARPC (Response Cryptogram) > Gera o ARPC (Authorization Response Cryptogram) a partir do ARQC recebido no campo 55 da transação EMV.\ > Retorna o ARPC gerado em \`retMultiValue\[0]\` em formato Hex.\ > \ > O campo \`field55EmvTags\` deve conter os dados EMV da transação em formato TLV hexadecimal.\ > Os campos \`arc\` e \`csu\` são utilizados dependendo do \`mode\` de operação.\ > \ > Em caso de erro, retorna os campos de erro (\`retCode\` e \`retDesc\`).
```json {"openapi":"3.0.3","info":{"title":"PayShield EMV API","version":"4.1.32"},"tags":[{"name":"EMV","description":"Operações de geração e validação de criptogramas EMV (ARPC/ARQC)"}],"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":{"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"}}},"ReturnMultiValue":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValue":{"type":"string","nullable":true},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Array com os valores de retorno — `retMultiValue[0]` contém o ARPC gerado em Hex"},"retValid":{"type":"boolean"},"retDesc":{"type":"string"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro:\n- `01`: Falha na verificação do ARQC/TC/AAC/MPVV\n- `03`: Padding Flag inválido\n- `04`: Mode Flag não reconhecido\n- `05`: Scheme ID não reconhecido\n- `06`: Valor YHHHHCC inválido\n- `10`: Erro de paridade na chave MK\n- `52`: Branch/Height inválido\n- `68`: Comando desabilitado\n- `F1`: Método de derivação de chave inválido\n- `F2`: Método de validação ARQC inválido\n- `F3`: Algoritmo da chave MK-AC não é AES\n- `F5`: Método de chave de sessão inválido\n- `F8`: Método de geração de chave OTPK inválido\n"},"retValue":{"type":"string"},"retMultiValue":{"nullable":true},"retValid":{"type":"boolean"},"retDesc":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldEMV/GenerateARQC4x":{"post":{"tags":["EMV"],"summary":"Gerar ARPC (Response Cryptogram)","description":"Gera o ARPC (Authorization Response Cryptogram) a partir do ARQC recebido no campo 55 da transação EMV.\nRetorna o ARPC gerado em `retMultiValue[0]` em formato Hex.\n\nO campo `field55EmvTags` deve conter os dados EMV da transação em formato TLV hexadecimal.\nOs campos `arc` e `csu` são utilizados dependendo do `mode` de operação.\n\nEm caso de erro, retorna os campos de erro (`retCode` e `retDesc`).\n","operationId":"generateARQC4x","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/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"},"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"}}}}}}}}} ``` ## Modelos de Objeto Esta seção detalha os modelos de objeto utilizados pelos endpoints EMV. Todos os modelos seguem a convenção de nomenclatura adotada na Hop V4. ### Arpcinput (Modelo de Request) Modelo único de request, utilizado por ambos os endpoints.
CampoTipoObrigatórioObservação
client_idinteger (int64, min 1)SimIdentificador do cliente.
brandstring (enum)SimMASTERCARD, VISA ou AMEX.
modestringSimModo de operação — ver seção 4.
schemeIdstringSimEsquema EMV — ver seção 5.
iv_acstring (nullable)NãoIV do AC — null quando não aplicável.
branch_height_paramsstring (nullable)NãoParâmetros de árvore de chaves.
mkacKeyIdstringSimIdentificador da chave MK-AC do emissor.
panstringSimPrimary Account Number.
panSeqNrstringSimPSN — usar "00" se não disponível.
field55EmvTagsstringSimCampo 55 em TLV hexadecimal.
arcstring (nullable)CondicionalObrigatório para mode = 1, 2, 5, 6, 9.
csustring (nullable)CondicionalObrigatório para mode = 3, 4, 5, 6.
arqcstring (nullable)NãoSobrescreve o ARQC da tag 9F26.
### Modelos de Resposta (Responses) #### ReturnSingle (Response de `ValidateARQC4x` com sucesso): * `retCode` (integer): `0` indica sucesso. * `retValue` (string): ARPC gerado em hexadecimal (modos de validação + geração). * `retValid` (boolean): `true` se validado com sucesso. * `retDescription` (string): Descrição textual do resultado. #### ReturnMultiValue (Response de `GenerateARPC4x` com sucesso): * `retCode` (integer): `0` indica sucesso. * `retValue` (string): Sempre vazio em caso de sucesso. * `retMultiValue` (string\[]): Array; `retMultiValue[0]` contém o ARPC gerado. * `retValid` (boolean): Indica operação bem-sucedida. * `retDesc` (string): Descrição textual do resultado. ReturnError (Response de Erro - 400, 404, 500) : * `retCode` (integer): Código de erro específico (ver taxonomia). * `retValue` (string): Não utilizado. * `retMultiValue` (any): Não utilizado. * `retValid` (boolean): `false` em erros. * `retDesc` (string): Descrição textual 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-emv/referencia-da-api-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.