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.