Digital signature algorithms

Last Updated: 31 October 2022

In the normal flow of a transaction being performed through either the hosted payments page or payment widget, the outcome of the transaction is communicated back to your website through means of a redirect call. While transaction outcomes can be queried both through the API or the user management portal, a further measure has been implemented to ensure that the details sent are checked for integrity and authenticity.

Hosted Payment Page

Whilst processing payments using the Hosted Payment Page, a signature can be sent in with the request to ensure the request payload has not been tampered with.

A signature is generated and sent as follows:

Take the JSON payload that you have generated when requesting the payment page.
Stringify that payload, for example using the built-in JSON.stringify() method for javascript or json.dumps() for python code.
Encode the resultant string and Secret Phrase, provided to you by Truevo, into UTF-8 format.
Pass these two values into the HMAC module from the HMAC library and utilise SHA-512 to generate a hash-based message authentication code.
The hash code is converted to hexadecimal and uppercased as per industry standards.
The generated signature must then be included as a header with a key named “signature”.

Payment Widget

Whilst processing payments using the Payment Widget, a signature can be set in the widget configuration object to ensure the request payload that will be sent has not been tampered with.

A signature for the payment widget is generated and sent as follows:

Generate the signature request by using the TruevoCheckout.retrieveRequestForSigning function while passing the configuration object into it as a parameter
Using a secure process only accessible to your server:
1. Encode the returned string and Secret Phrase, provided to you by Truevo, into UTF-8 format.
2. Pass these two values into the HMAC module from the HMAC library and utilise SHA-512 to generate a hash-based message authentication code.
The hash code is converted to hexadecimal and uppercased as per industry standards.
The generated signature must then be added to the configuration objects signature parameter before the TruevoCheckout.initialize and TruevoCheckout.mount functions are called.

Code example for Payment Widget Signature

JavaScript

				
					const configuration = {
      transactionType: 'sale',
      transaction: {
        paymentReference: 'Camp Website"',
        merchantReference: 'Order 123',
        amount: {
          totalAmount: 0.99,
          currencyAlphaCode: 'EUR' 
       }
      },
      merchant: {
        mid: '999999',
        tid: '000000'
      },
	  additionalData: []
    };

var requestToSign = TruevoCheckout.retrieveRequestForSigning(configuration);
var signature = SecureSignatureGenerationMethod(requestToSign);
configuration.signature = signature.toUpperCase();
TruevoCheckout.initialize(configuration);

Digital Signature Code Examples

C#

				
					using System;
using System.Security.Cryptography;
using System.Text;

namespace signature_c
{
    class Program
    {
        static void Main(string[] args)
        {
            var request = "{\"merchant\":{\"mid\":\"00060915\",\"tid\":\"99060915\",\"redirectUrl\":\"testurl.com\"},\"transaction\":{\"amount\":{\"totalAmount\":5.50,\"currencyAlphaCode\":\"GBP\",\"details\":{\"paymentAmount\":5.50,\"gratuityAmount\":0.00}},\"source\":\"ECOMMERCE\",\"transactionUniqueIdentifier\":\"\",\"merchantReference\":\"ABC001\",\"paymentReference\":\"00001\"}}";
            var salt = "MySecret";
            GenerateSignature(salt, request);
        }


        public static void GenerateSignature(string salt, String raw)
        {
            var saltBytes = Encoding.UTF8.GetBytes(salt);
            
            using (HMACSHA512 hmac = new HMACSHA512(saltBytes))
            { 
                var toHash = Encoding.UTF8.GetBytes(raw); 
                byte[] hashValue = hmac.ComputeHash(toHash);
                var hexString = BitConverter.ToString(hashValue);
                hexString = hexString.Replace("-", "");
                Console.WriteLine(hexString);
            }
        } 
    }
}

Python

				
					import hmac
import json
from hashlib import sha512

request = "{\"merchant\":{\"mid\":\"00060915\",\"tid\":\"99060915\",\"redirectUrl\":\"testurl.com\"},\"transaction\":{\"amount\":{\"totalAmount\":5.50,\"currencyAlphaCode\":\"GBP\",\"details\":{\"paymentAmount\":5.50,\"gratuityAmount\":0.00}},\"source\":\"ECOMMERCE\",\"transactionUniqueIdentifier\":\"\",\"merchantReference\":\"ABC001\",\"paymentReference\":\"00001\"}}"

str_to_hash: str = json.dumps(request, separators=(",", ":"))

signature = hmac.new(
    salt.encode("utf-8"), str_to_hash.encode("utf-8"), sha512
).hexdigest().upper()

print(signature)

JavaScript

				
					var crypto = require('crypto');

var raw = JSON.stringify({
    "merchant":
    {
        "mid": "00060915",
        "tid": "99060915",
        "redirectUrl": "testurl.com"
    },
    "transaction":
    {
        "amount":
        {
            "totalAmount": 5.50,
            "currencyAlphaCode": "GBP",
            "details":
            {
                "paymentAmount": 5.50,
                "gratuityAmount": 0.00
            }
        },
        "source": "ECOMMERCE",
        "transactionUniqueIdentifier": "",
        "merchantReference": "ABC001",
        "paymentReference": "00001"
    }
});

var hmac = crypto.createHmac('sha512', 'MySecret');
data = hmac.update(raw);
gen_hmac= data.digest('hex').toUpperCase();
console.log(gen_hmac);

Digital signature algorithms

Hosted Payment Page

Payment Widget

Code example for Payment Widget Signature

JavaScript

Digital Signature Code Examples

C#

Python

JavaScript

Page Contents