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