HMAC Generation

This page aims to guide the implementation of the HMAC calculation for access to our APIs. HMAC is a new security layer to ensure correct caller identification.

Basically, this layer works by including an electronically generated signature in calls. Our APIs, upon receiving this call, will recalculate the same signature and match it with the signature sent.

Requirements

You will need to have the following information, which is normally already used in calls without this authentication layer:

• API Key: Your identification as a customer. Your customer code, or Merchant ID.
• Secret Key: Your security key. In calls without this layer, it is sent as Merchant Key. In calls using HMAC, this information is never sent. It only participates in the calculation.

Adapting your calls

The examples below will behave in the same way as the examples mentioned on the pagemento page.

Considering a simple call as illustrated below:

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

Let's make the following changes to make it compatible with the new security layer.

• Step 1: Place the script below in your Postsman as a pre-req script:

var uuid = require('uuid');

// Your identification in the new authentication process via HMAC (API Key)

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

// Your secret key to be used in the new authentication process via HMAC (Secret Key)

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

var correlationId = uuid.v4(); // unique code to identify the transaction

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

• Step 2: Set the following header variables in your Postman:

Parameter	Description	Format	Mandatory
Content-Type	Must be sent with the value application/json.	= 15 AN	YES
merchant_id	Store code in Carat. The production and certification codes will be different.	< 15 AN	YES
merchant_key	Store authentication key in Carat. The production and certification keys will be different.	< 80 AN	YES
Auth-Token-Type	Identification of the authentication type used in the call. In this case, HMAC	< 10 AN	YES
Authorization	Result generated in the JavaScript routine of Step 1. In Postman, {Authorization} can be used to get the environment variable created by the Script	< 250 AN
Timestamp	Must contain the numeric representation of the date and time. In Postman, {time} can be used to get the environment variable created by the Script	< 15 N	YES
Client-Request-Id	This field will contain a generated and unique number to be propagated throughout the life of the transaction.	< 100 N	YES
api-key	This will contain your key for access via HMAC. This should be provided by Fiserv.	< 100 N	YES

• Step 3: Execute the call:

After the changes, the new curl generated by Postman would look something like this:

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

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

--header 'merchant_id: MERCHANT_EXAMPLE_ID' \

--header 'merchant_key: MERCHANT_EXAMPLE_KEY_ABCDEF' \

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

--header 'Authorization: SINGATURE_ENCRIPTED_GENERATED' \

--header 'Timestamp: 1749674373790' \

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

--header 'api-key: YOUR_KEY_FOR_HMAC_SENT_BY_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"

}

}'

The above example will behave just like the other calls on the payment page.