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âmetro

Valor

Base URL (API)

https://apivin.first-tech.net [A confirmar host definitivo de PRD/HML]

Endpoint de autenticação

https://auth.first-tech.net/oauth/token

grant_type

client_credentials

audience

https://auth-jwt-authorize-prd-first-tech

token_type

Bearer

Tempo de vida (padrão)

[A confirmar TTL do token com a equipa técnica]

Cabeçalhos Obrigatórios (`Headers`):

HTTP
Authorization: Bearer <TOKEN_JWT>
Content-Type: application/json
Accept: */*

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.

POST /ValidateARQC4x

Validar ARQC (Request Cryptogram)

post

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).

Authorizations

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

client_idinteger · int64 · min: 1Required

Identificador do cliente

Example: 8

brandstring · enumRequired

Bandeira do cartão

Example: MASTERCARDPossible values:

modestringRequired

Modo de operação do comando EMV:

0: Validar ARQC
1: Validar ARQC e gerar ARPC método 1 (ARC)
2: Gerar ARPC método 1 (ARC) sem validar ARQC
3: Validar ARQC e gerar ARPC método 2 (CSU)
4: Gerar ARPC método 2 (CSU) sem validar ARQC
5: Validar ARQC e gerar ARPC métodos 1 e 2
6: Gerar ARPC métodos 1 e 2 sem validar ARQC
8: Validar TC/AAC
9: Validar TC/AAC e gerar ARPC método 1

Example: 1

schemeIdstringRequired

Identificador do esquema EMV:

0: Visa VIS (CVN 10 ou 17)
1: Mastercard M/Chip (CVN 10 ou 11)
2: American Express AEIPS
3: Mastercard M/Chip com PAN length
5: Visa VIS com PAN length
6: JCB
7: Discover
9: Visa qVSDC
A: Mastercard PayPass
B: Mastercard PayPass com PAN length
C: Mastercard PayPass com padding flag

Example: 3

iv_acstring · nullableOptional

IV para derivação de chave de sessão EMV 2000. Obrigatório apenas para schemeId = 0 ou 1.

branch_height_paramsstring · nullableOptional

Parâmetros de branch/height para derivação de chave de sessão EMV 2000. Obrigatório apenas para schemeId = 0 ou 1.

0: Branch factor 2, Tree Height 16
1: Branch factor 4, Tree Height 8

mkacKeyIdstringRequired

Alias/identificador da chave MKAC no banco de dados

Example: client-8-key-id-666-MKAC-T2

panstringRequired

PAN do cartão

Example: 1111222233334444

panSeqNrstringRequired

Número de sequência do PAN (PSN) — usar 00 se não disponível

Example: 00

field55EmvTagsstringRequired

Dados EMV da transação em formato TLV hexadecimal (campo 55 da ISO 8583). O ARQC é extraído automaticamente da tag 9F26. Tags relevantes utilizadas: 9F26 (ARQC), 9F36 (ATC), 9F10 (Issuer Application Data), 8C (CDOL1).

Example:

9F2608970654A94F74DA109F02060000000495769F03060000000000009F1A020076950580000480005F2A0209869A032203299C01009F37041664B560820239009F360200989F10120114A00001220000000000000000000000FF

arcstring · nullableOptional

Authorization Response Code — obrigatório para mode = 1, 2, 5, 6 ou 9. Valor em Hex (ex: 00 = aprovado, 01 = negado).

Example: 00

arqcstring · nullableOptional

ARQC (Authorization Request Cryptogram) em Hex. Quando informado, sobrescreve o valor extraído automaticamente da tag 9F26 do field55EmvTags. Utilizado principalmente no endpoint ValidateARQC4x.

Example: 8B7864F9F117E609

csustring · nullableOptional

Card Status Update — obrigatório para mode = 3, 4, 5 ou 6. 4 bytes em Hex.

Example: 03820000

Responses

200

Operação realizada com sucesso

application/json

retCodeintegerOptional

Código de retorno. 0 = sucesso, outros valores indicam erro

Example: 0

retValuestring · nullableOptional

ARPC gerado em Hex (quando aplicável)

Example: 70EFBFBDD89DEFBF

retValidbooleanOptional

Indica se o ARQC foi validado com sucesso

Example: true

retDescriptionstringOptionalExample: OK

400

Requisição inválida

application/json

401

Não autorizado — token Bearer ausente ou inválido

404

Chave não encontrada no banco de dados

application/json

500

Erro interno do servidor

application/json

post/v4/PayShieldEMV/ValidateARQC4x

POST /v4/PayShieldEMV/ValidateARQC4x HTTP/1.1
Host: apivin.first-tech.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 442

{
  "client_id": 8,
  "brand": "MASTERCARD",
  "mode": "1",
  "schemeId": "3",
  "iv_ac": null,
  "branch_height_params": null,
  "mkacKeyId": "client-8-key-id-666-MKAC-T2",
  "pan": "1111222233334444",
  "panSeqNr": "00",
  "field55EmvTags": "9F2608970654A94F74DA109F02060000000495769F03060000000000009F1A020076950580000480005F2A0209869A032203299C01009F37041664B560820239009F360200989F10120114A00001220000000000000000000000FF",
  "arc": "00",
  "arqc": "8B7864F9F117E609",
  "csu": "03820000"
}

{
  "retCode": 0,
  "retValue": "70EFBFBDD89DEFBF",
  "retValid": true,
  "retDescription": "OK"
}

POST /GenerateARPC4x

Gerar ARPC (Response Cryptogram)

post

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).

Authorizations

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

client_idinteger · int64 · min: 1Required

Identificador do cliente

Example: 8

brandstring · enumRequired

Bandeira do cartão

Example: MASTERCARDPossible values:

modestringRequired

Modo de operação do comando EMV:

0: Validar ARQC
1: Validar ARQC e gerar ARPC método 1 (ARC)
2: Gerar ARPC método 1 (ARC) sem validar ARQC
3: Validar ARQC e gerar ARPC método 2 (CSU)
4: Gerar ARPC método 2 (CSU) sem validar ARQC
5: Validar ARQC e gerar ARPC métodos 1 e 2
6: Gerar ARPC métodos 1 e 2 sem validar ARQC
8: Validar TC/AAC
9: Validar TC/AAC e gerar ARPC método 1

Example: 1

schemeIdstringRequired

Identificador do esquema EMV:

0: Visa VIS (CVN 10 ou 17)
1: Mastercard M/Chip (CVN 10 ou 11)
2: American Express AEIPS
3: Mastercard M/Chip com PAN length
5: Visa VIS com PAN length
6: JCB
7: Discover
9: Visa qVSDC
A: Mastercard PayPass
B: Mastercard PayPass com PAN length
C: Mastercard PayPass com padding flag

Example: 3

iv_acstring · nullableOptional

IV para derivação de chave de sessão EMV 2000. Obrigatório apenas para schemeId = 0 ou 1.

branch_height_paramsstring · nullableOptional

Parâmetros de branch/height para derivação de chave de sessão EMV 2000. Obrigatório apenas para schemeId = 0 ou 1.

0: Branch factor 2, Tree Height 16
1: Branch factor 4, Tree Height 8

mkacKeyIdstringRequired

Alias/identificador da chave MKAC no banco de dados

Example: client-8-key-id-666-MKAC-T2

panstringRequired

PAN do cartão

Example: 1111222233334444

panSeqNrstringRequired

Número de sequência do PAN (PSN) — usar 00 se não disponível

Example: 00

field55EmvTagsstringRequired

Example:

9F2608970654A94F74DA109F02060000000495769F03060000000000009F1A020076950580000480005F2A0209869A032203299C01009F37041664B560820239009F360200989F10120114A00001220000000000000000000000FF

arcstring · nullableOptional

Authorization Response Code — obrigatório para mode = 1, 2, 5, 6 ou 9. Valor em Hex (ex: 00 = aprovado, 01 = negado).

Example: 00

arqcstring · nullableOptional

Example: 8B7864F9F117E609

csustring · nullableOptional

Card Status Update — obrigatório para mode = 3, 4, 5 ou 6. 4 bytes em Hex.

Example: 03820000

Responses

200

Operação realizada com sucesso

application/json

retCodeintegerOptional

Código de retorno. 0 = sucesso, outros valores indicam erro

Example: 0

retValuestring · nullableOptional

retMultiValuestring[] · nullableOptional

Array com os valores de retorno — retMultiValue[0] contém o ARPC gerado em Hex

Example: ["70EFBFBDD89DEFBF"]

retValidbooleanOptionalExample: true

retDescstringOptionalExample: OK

400

Requisição inválida

application/json

401

Não autorizado — token Bearer ausente ou inválido

404

Chave não encontrada no banco de dados

application/json

500

Erro interno do servidor

application/json

post/v4/PayShieldEMV/GenerateARQC4x

POST /v4/PayShieldEMV/GenerateARQC4x HTTP/1.1
Host: apivin.first-tech.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 416

{
  "client_id": 8,
  "brand": "MASTERCARD",
  "mode": "1",
  "schemeId": "3",
  "iv_ac": null,
  "branch_height_params": null,
  "mkacKeyId": "client-8-key-id-666-MKAC-T2",
  "pan": "1111222233334444",
  "panSeqNr": "00",
  "field55EmvTags": "9F2608970654A94F74DA109F02060000000495769F03060000000000009F1A020076950580000480005F2A0209869A032203299C01009F37041664B560820239009F360200989F10120114A00001220000000000000000000000FF",
  "arc": "00",
  "csu": "03820000"
}

{
  "retCode": 0,
  "retValue": "",
  "retMultiValue": [
    "70EFBFBDD89DEFBF"
  ],
  "retValid": true,
  "retDesc": "OK"
}

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.

Campo

Tipo

Obrigatório

Observação

client_id

integer (int64, min 1)

Sim

Identificador do cliente.

brand

string (enum)

Sim

MASTERCARD, VISA ou AMEX.

mode

string

Sim

Modo de operação — ver seção 4.

schemeId

string

Sim

Esquema EMV — ver seção 5.

iv_ac

string (nullable)

Não

IV do AC — null quando não aplicável.

branch_height_params

string (nullable)

Não

Parâmetros de árvore de chaves.

mkacKeyId

string

Sim

Identificador da chave MK-AC do emissor.

pan

string

Sim

Primary Account Number.

panSeqNr

string

Sim

PSN — usar "00" se não disponível.

field55EmvTags

string

Sim

Campo 55 em TLV hexadecimal.

arc

string (nullable)

Condicional

Obrigatório para mode = 1, 2, 5, 6, 9.

csu

string (nullable)

Condicional

Obrigatório para mode = 3, 4, 5, 6.

arqc

string (nullable)

Não

Sobrescreve 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

PreviousModos de Operação e Bandeiras NextCódigos de Erro e Troubleshooting

Last updated 3 months ago

Autenticação e Base URL

Configurações de Conexão:

Cabeçalhos Obrigatórios (Headers):

Estratégia de Renovação de Token:

POST /ValidateARQC4x

Validar ARQC (Request Cryptogram)

POST /GenerateARPC4x

Gerar ARPC (Response Cryptogram)

Modelos de Objeto

Arpcinput (Modelo de Request)

Modelos de Resposta (Responses)

ReturnSingle (Response de ValidateARQC4x com sucesso):

ReturnMultiValue (Response de GenerateARPC4x com sucesso):

Cabeçalhos Obrigatórios (`Headers`):

ReturnSingle (Response de `ValidateARQC4x` com sucesso):

ReturnMultiValue (Response de `GenerateARPC4x` com sucesso):