# How to Create an HMAC Signature source: https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/tutorials-and-guides/how-to-create-hmac-signature/index.md This article walks you through the process for creating an HMAC signature, which is used to validate that the message originates from a trusted source. ## Overview {#overview} The HMAC signature is based on the following API request data elements, concatenated using a new line character. Note that the elements must be in this order: * Host * Canonicalized Resource * Request Body string (without spaces) * HTTP Verb * Content-Type (POST request content type: "application/json") * Request Timestamp in UTC ### Base64 URL-Safe Encoding {#base64-url-safe-encoding} The computed HMAC hash string must be encoded using Base64 URL-safe encoding. The url-safe variation uses '-' and '_' instead of '+' and '/' characters, respectively, and strips out '=' characters. ### Signature Verification Example {#signature-verification-example} ```text POST https://merchant.com:443/api/orders HTTP/1.1 Accept: application/json Accept-Encoding: gzip, deflate Content-Type: application/json Host: merchant.com User-Agent: Ethoca-purchase-inquirer (version 3.0) X-Eth-Date: 2017-06-19T13:18:18Z Authorization: ETHOCA-SHA1 KeyRef=,Signature= Post request body: { "requestReference": { "originatorChannel": "DIGITAL", "originatorId": "420f0845bd9b808abd7acc053b0b372ceb461edd584e9b9db02b35304255715f", "sourceId": "66666688ggg0845bd9b808abd7acc053b0b372ceb461edd584e9b9db02b324gf", "originatorDescription": "Test Issuer", "correlationId": "zebj8evpeo", "locale": "en-US" }, "searchCriteria": { "paymentType": "MC", "transactionIdentifierType": "BANKNET_REF_NUM", "transactionIdentifierValue": "90989JJJNM7767", "acquirerReferenceNumber": "12345678901234567890123", "transactionDateTime": "2020-06-18T17:11:05-05:00", "cardFirstSix": "123456", "cardLastFour": "1234", "issuerAuthorizationCode": "123456", "transactionAmount": "250.35", "transactionCurrencyCode": "USD", "merchantId": "GHF5F67DFSD468GJJXH78", "cardAcceptorName": "Ethoca Chairs", "cardAcceptorLocation": "Austin", "cardAcceptorRegionCode": "TX", "cardAcceptorCountryCode": "US", "disputeCriteriaDisputeId": "52318413-bd05-4960-a745-f79e5c3d6de9", "disputeCriteriaDisputeIdType": "CLAIM_ID", "clearingDateTime": "2020-11-04T22:11:05.000Z", "clearingAmountValue": "250.0", "clearingAmountCurrencyCode": "USD" } } ``` ## Create your HMAC Signature {#create-your-hmac-signature} Follow these steps to create your required HMAC signature: Note: The sample values in these steps are for example only. Use your own values when creating the HMAC signature. 1. Convert the following data elements to HEX. You can use the tool at [String to Bytes Converter](https://onlinestringtools.com/convert-string-to-bytes) to get your HEX output. Paste your data elements in the **Input String** box and the output is displayed in the **Output Bytes** section. Note that each input data element is separated by a new line, which equates to HEX character "0A" in the converted HEX output. | Data Element | Example | |--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Host | merchant.com | | Canonicalized Resource | `https://merchant.com:443/api/orders` | | Request Body String | {"requestReference":{"originatorChannel":"DIGITAL","originatorId":"420f0845bd9b808abd7acc053b0b372ceb461edd584e9b9db02b35304255715f","sourceId":"66666688ggg0845bd9b808abd7acc053b0b372ceb461edd584e9b9db02b324gf","originatorDescription":"Test Issuer","correlationId":"zebj8evpeo","locale":"en-US"},"searchCriteria":{"paymentType":"MC","transactionIdentifierType":"BANKNET_REF_NUM","transactionIdentifierValue":"90989JJJNM7767","acquirerReferenceNumber":"12345678901234567890123","transactionDateTime":"2020-06-18T17:11:05-05:00","cardFirstSix":"123456","cardLastFour":"1234","issuerAuthorizationCode":"123456","transactionAmount":"250.35","transactionCurrencyCode":"USD","merchantId":"GHF5F67DFSD468GJJXH78","cardAcceptorName":"Ethoca Chairs","cardAcceptorLocation":"Austin","cardAcceptorRegionCode":"TX","cardAcceptorCountryCode":"US"}} | | HTTP Verb | POST | | Content-Type | application/json | | Request Timestamp in UTC | 2017-06-19T13:18:18Z | Example data elements to convert: ```text merchant.com https://merchant.com:443/api/orders {"requestReference":{"originatorChannel":"DIGITAL","originatorId":"420f0845bd9b808abd7acc053b0b372ceb461edd584e9b9db02b35304255715f","sourceId":"66666688ggg0845bd9b808abd7acc053b0b372ceb461edd584e9b9db02b324gf","originatorDescription":"Test Issuer","correlationId":"zebj8evpeo","locale":"en-US"},"searchCriteria":{"paymentType":"MC","transactionIdentifierType":"BANKNET_REF_NUM","transactionIdentifierValue":"90989JJJNM7767","acquirerReferenceNumber":"12345678901234567890123","transactionDateTime":"2020-06-18T17:11:05-05:00","cardFirstSix":"123456","cardLastFour":"1234","issuerAuthorizationCode":"123456","transactionAmount":"250.35","transactionCurrencyCode":"USD","merchantId":"GHF5F67DFSD468GJJXH78","cardAcceptorName":"Ethoca Chairs","cardAcceptorLocation":"Austin","cardAcceptorRegionCode":"TX","cardAcceptorCountryCode":"US"}} POST application/json 2017-06-19T13:18:18Z ``` Which converts to this HEX output: ```text 6d65726368616e742e636f6d0a68747470733a2f2f6d65726368616e742e636f6d3a3434332f6170692f6f72646572730a7b22726571756573745265666572656e6365223a7b226f726967696e61746f724368616e6e656c223a224449474954414c222c226f726967696e61746f724964223a2234323066303834356264396238303861626437616363303533623062333732636562343631656464353834653962396462303262333533303432353537313566222c22736f757263654964223a2236363636363638386767673038343562643962383038616264376163633035336230623337326365623436316564643538346539623964623032623332346766222c226f726967696e61746f724465736372697074696f6e223a225465737420497373756572222c22636f7272656c6174696f6e4964223a227a65626a38657670656f222c226c6f63616c65223a22656e2d5553227d2c227365617263684372697465726961223a7b227061796d656e7454797065223a224d43222c227472616e73616374696f6e4964656e74696669657254797065223a2242414e4b4e45545f5245465f4e554d222c227472616e73616374696f6e4964656e74696669657256616c7565223a2239303938394a4a4a4e4d37373637222c2261637175697265725265666572656e63654e756d626572223a223132333435363738393031323334353637383930313233222c227472616e73616374696f6e4461746554696d65223a22323032302d30362d31385431373a31313a30352d30353a3030222c22636172644669727374536978223a22313233343536222c22636172644c617374466f7572223a2231323334222c22697373756572417574686f72697a6174696f6e436f6465223a22313233343536222c227472616e73616374696f6e416d6f756e74223a223235302e3335222c227472616e73616374696f6e43757272656e6379436f6465223a22555344222c226d65726368616e744964223a224748463546363744465344343638474a4a58483738222c22636172644163636570746f724e616d65223a224574686f636120436861697273222c22636172644163636570746f724c6f636174696f6e223a2241757374696e222c22636172644163636570746f72526567696f6e436f6465223a225458222c22636172644163636570746f72436f756e747279436f6465223a225553227d7d0a504f53540a6170706c69636174696f6e2f6a736f6e0a323031372d30362d31395431333a31383a31385a ``` Note: All spaces are removed only if you uncheck the "Add a Whitespace" box in the tool. Every "0A" indicates a new line. 2. Go to and paste your concatenated HEX output into the **Input** field of the HMAC converter. Use these settings to generate your output: * **Input Type** = HEX * **Key** = weing1phojieRaht * **Key type** = Text * **SHA variant** = SHA-1 * **Output Type** = HEX The output is your HEX HMAC Signature String, which will be converted into Base64 encoding in the next step.
3. Go to and paste your HEX HMAC Signature String into the **Hex\*** field. Then select **Convert Hex to Base64**. Your Base64 Encoded Signature is output in the **Base64** field.
4. Go to and paste your Base64 Encoded Signature into the top input box. Your Base64 URL-Safe Encoded Signature is output in the second output box with the header **Base64 Url Safe Text**, and this encoded signature is what you will use for your required HMAC signature header. The Base64 URL-Safe Encoded Signature for the **Example data elements** shown above is **blJKZStXSWQvZCtYVmNYL29zbXNoVGZ3YzZVPQ**. ## Next Steps {#next-steps} * Walk through our [Reference App Tutorial](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/tutorials-and-guides/reference-app-tutorial/index.md) for step-by-step guidance in simulating how your API should interact with the Merchant Transaction API. * See [Integration and Testing](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/testing/index.md) for help with conducting thorough testing of the integration to ensure the foundational functionality is in place.