The seal (received in the Hmac field) is calculated using a cryptographic hash function in combination with a merchant key that complies with the specifications of RFC 2104. This function will generate the seal from the data to be certified and the merchant security key in its octal form.
It is the merchant's responsibility to calculate the seal with the data received during the payment notification and compare it with the value received in the Hmac field to ensure that the data has not been corrupted.
Some fields, which are optional in the payment page call form, are mandatory in the hash string. If these optional fields are not sent, only the delimiters ("*") must be present in this string.
Some data are not mandatory, so they will not have to be certified if they are not present when the payment confirmation is received.
Points of attention when calculating the seal :
• The spaces at the beginning and at the end of each field are removed (Trim).
• Specify the encoding of the character string used for the calculation of the HMAC seal (to check if it is compatible with the encoding set up for the merchant).
• The order of the fields can be different within the different HMAC seals used during the process.
It is the merchant's responsibility to keep the key used by the hash function secure and confidential by using the best tools available in their environment.
This key will be provided by Floa.
The security key is represented by 40 hexadecimal characters (for example: 0123456789ABCDEF0123456789ABCDEF01234567). This representation must be converted to a 20-byte string before use.
Data to be certified upon receipt of the payment confirmation
| Data | Hash chain |
|---|---|
| Version | To be certified |
| MerchantID | To be certified |
| MerchantSiteID | To be certified |
| PaymentOptionRef | To be certified |
| OrderRef | To be certified |
| OrderTag | Do not certify if not received |
| FreeText | Keep the delimiter * if not received |
| DecimalPosition | To be certified |
| Currency | To be certified |
| Country | To be certified |
| InvoiceId | Keep the delimiter * if not received |
| CustomerRef | To be certified |
| Date | To be certified |
| Amount | To be certified |
| ReturnCode | To be certified |
| MerchantAccountRef | Keep the delimiter * if not received |
| ScheduleDate1..n | Do not certify if not received. Do not certify if paid 1XD/1XC |
| ScheduleAmount1..n | Do not certify if not received. Do not certify if paid 1XD/1XC |
| CardType | Not to be certified |
| CardSubtype | Not to be certified |
| StoredCardID1..n | Do not certify if not received |
| StoredCardLabel1..n | Do not certify if not received |
| reportDelayInDays | Do not certify if not received |
| scoringToken | Not to be certified |
Examples of hash strings when receiving the payment confirmation
Example of a hash string with all the data :
Version*merchantID*merchantSiteID*paymentOptionRef*orderRef*orderTag*freeText*decimalPosition*currency*country*invoiceID*customerRef*date*amount*returnCode*merchantAccountRef*[scheduleDate1*scheduleAmount1*[scheduleDateN*scheduleAmountN*]]reportDelayInDays*
Example of hash chain with minimal data :
Version*merchantID*merchantSiteID*paymentOptionRef*orderRef**decimalPosition*currency*country**customerRef*date*amount*returnCode**
Example of hash string for a 3X command :
Version*merchantID*merchantSiteID*paymentOptionRef*orderRef*orderTag*freeText*decimalPosition*currency*country*invoiceID*customerRef*date*amount*returnCode*merchantAccountRef*scheduleDate1*scheduleAmount1*scheduleDate2*scheduleAmount2*scheduleDate3*scheduleAmount3*
Code example
private static string ComputeHMACSHA1_UTF8(string key, string value)
{
// 1. Converts key and value into byte array.
byte[] keyBytes = UTF8Encoding.UTF8.GetBytes(key);
byte[] valueBytes = UTF8Encoding.UTF8.GetBytes(value);
// 2. Initialize hmac computer
HMACSHA1 hmacSha1Computer = new HMACSHA1(keyBytes);
// 3. Performs hash
byte[] hmacBytes = hmacSha1Computer.ComputeHash(valueBytes);
// 4. Format the hash into string format.
return BitConverter.ToString(hmacBytes).Replace("-", string.Empty);
}
hash_hmac(‘sha1’, $value, $key, false);
Example of a Hash calculation
With this notification :
version:1.0
merchantID:38
merchantSiteID:7936
paymentOptionRef:81
orderRef:WFP2868151681904334
freeText:
invoiceID:0
customerRef:1841251
date:20230419
amount:151500
decimalPosition:2
currency:EUR
country:FR
returnCode:0
merchantAccountRef:FINBCA4627@SIPSV2
scheduleDate1:20230419
scheduleAmount1:50500
scheduleDate2:20230519
scheduleAmount2:50500
scheduleDate3:20230618
scheduleAmount3:50500
cardType:CB
cardSubtype:None
scoringToken:3df42507-1ce1-4b64-9cee-9e45e869c88b
hmac:F39234CEFFC455EE5754FABA75AA8599CA2E553F
The Chain to compute Hash is :
Version*merchantID*merchantSiteID*paymentOptionRef*orderRef**decimalPosition*currency*country*invoiceID*customerRef*date*amount*returnCode*merchantAccountRef*scheduleDate1*scheduleAmount1*scheduleDate2*scheduleAmount2*scheduleDate3*scheduleAmount3*
With the values of the notification :
1.0*38*7936*81*WFP2868151681904334**2*EUR*FR*0*1841251*20230419*151500*0*FINBCA4627@SIPSV2*20230419*50500*20230519*50500*20230618*50500*
The HASH key for merchantID is 336AC9E91CE394145B177CD14807D4F199A6AC74
Result with SHA1 algorithm must be F39234CEFFC455EE5754FABA75AA8599CA2E553F
You can use this website to test your formula : https://www.freeformatter.com/hmac-generator.html#before-output
