Geração de HMAC

Está página tem como objetivo orientar a implementação do cálculo HMAC para acesso as nossas APIs. O HMAC é uma nova camada de segurança para garantir a correta identificação do chamador.

Basicamente, o funcionamento desta camada consiste em incluir uma assinatura eletronicamente gerada nas chamadas. As nossas APIs, ao receber esta chamada, irão recalculas a mesma assinatura e bater com a assinatura enviada.

Requisitos

Você precisará ter as seguintes informações, que normalmente já são usadas nas chamadas sem esta camada de autenticação:

• API Key: Sua identificação como cliente. O seu código de cliente, ou Merchant ID.
• Secret Key: Sua chave de segurança. Nas chamadas sem esta camada, ela é enviada como Merchant Key. Nas chamadas usando HMAC, esta informação nunca é enviada. Ela apenas participa do cálculo.

Adaptando suas chamadas

Os exemplos abaixo vão se comportar tal como os exemplos citados na página de pagemento.

Considerando uma chamada simples commo ilustrada abaixo:

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/payments/' \

--header 'Content-Type: application/json' \

--header 'merchant_id: MERCHANT_ID_DE_EXEMPLO' \

--header 'merchant_key: MERCHANT_KEY_DE_EXEMPLOABCDEF' \

--data-raw '{

"merchant_usn": "12050620649",

"order_id": "121314",

"installments": "10",

"installment_type": "4",

"authorizer_id": "2",

"amount": "10000",

"card": {

"expiry_date": "1222",

"security_code": "123",

"number": "5555555555555555"

}

}'

--verbose

Vamos fazer as seguintes alterações para torná-la compatível com a nova camada de segurança.

• Passo 1: Coloque o script abaixo no seu Postsman como pre-req script:

var uuid = require('uuid');

// Sua identificacao no novo processo de autenticacao via HMAC (API Key)

var key = pm.environment.get("hmacKey");

// Sua chave secreta a ser usada no novo processo de autenticacao via HMAC (Secret Key)

var secret = pm.environment.get("hmacSecret");

var correlationId = uuid.v4(); // codigo unico para identificar a transacao

postman.setEnvironmentVariable("correlationId", correlationId);

var time = new Date().getTime();

var method = pm.request.method;

var requestBody = pm.request.body;

var rawSignature = key + correlationId + time;

if(method != 'GET' && method != 'DELETE'){

rawSignature = rawSignature + requestBody;

}

var computedHash = CryptoJS.algo.HMAC.create(CryptoJS.algo.SHA256, secret.toString());

computedHash.update(rawSignature);

computedHash = computedHash.finalize();

var computedHmac = CryptoJS.enc.Base64.stringify(computedHash);

postman.setEnvironmentVariable('time', time);

postman.setEnvironmentVariable('Authorization', computedHmac);

• Passo 2: Configure as seguintes variáveis header no seu Postman:

Parâmetro	Descrição	Formato	Obrigatório
Content-Type	Deve ser enviado com o valor application/json.	= 15 AN	SIM
merchant_id	Código da loja no Carat. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
merchant_key	Chave de autenticação da loja no Carat. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM
Auth-Token-Type	Identificação do tipo de autenticação usado na chamada. No caso, HMAC	< 10 AN	SIM
Authorization	Resultado gerado na rotina JavaScript do Passo 1. No Postman, pode ser usado {Authorization} para pegar a variável de ambiente criada pelo Script	< 250 AN
Timestamp	Deve conter a representação numérica da data e hora. No Postman, pode ser usado {time} para pegar a variável de ambiente criada pelo Script	< 15 N	SIM
Client-Request-Id	Este campo irá conter um número gerado e único para ser propagado por toda a vida da transação.	< 100 N	SIM
api-key	Vai conter a sua chave para acesso via HMAC. Isso deverá ser fornecido pela Fiserv.	< 100 N	SIM

• Passo 3: Executar a chamada:

Após as mudanças, o novo curl gerado pelo Postman seria algo parecido com o seguinte:

curl --location 'https://connect-cert.latam.fiservapis.com/carat/e-sitef/api/v2/payments/' \

--header 'Content-Type: application/json' \

--header 'merchant_id: MERCHANT_ID_DE_EXEMPLO' \

--header 'merchant_key: MERCHANT_KEY_DE_EXEMPLOABCDEF' \

--header 'Auth-Token-Type: HMAC' \

--header 'Authorization: ASSINATURA_ENCRIPTADA_PARA_VALIDACAO_HMAC' \

--header 'Timestamp: 1749674373790' \

--header 'Client-Request-Id: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee' \

--header 'api-key: SUA_CHAVE_PARA_HMAC_ENVIADA_PELA_FISERV' \

--data '{

"merchant_usn": "12050620649",

"order_id": "12345",

"installments": "1",

"installment_type": "4",

"authorizer_id": "2",

"amount": "10000",

"card": {

"expiry_date": "0631",

"security_code": "929",

"number": "5485739238858589"

}

}'

O exemplo acima irá se comportar tal qual as demais chamadas na página de pagamento.