EMV

Endpoints do serviço ws-hop-api-emv

EMV Validate ARPC 4.x Module

post

Returns True or False according to the validation of the ARQC (Request Cryptogram) if it is valid or not, in retValid.

Authorizations

bearerAuth

AuthorizationstringRequired

Token JWT obtido via Auth0

Body

application/json

client_idinteger · int64 · min: 1Required

Identificador do cliente

Example: 99

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-99-key-id-XXXXX-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: 9F26081234567890ABCDEF9F02061234567890AB9F03060000000000009F1A020076950580000480005F2A0209869A031234569C01009F370412345678820239009F360200989F10120114A00001220000000000000000000000FF

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.

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

retValidbooleanOptional

Indica se o ARQC foi validado com sucesso

Example: true

retValuestring · nullableOptional

ARPC gerado em Hex (quando aplicável)

Example: 70EFBFBFD89DBFBF

retDescriptionstringOptional

Descrição do resultado

Example: 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

HTTPcURLJavaScriptPython

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

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

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