On This Page

Construct Messages Using HTTP Signature Security

HTTP signatures use a digital signature to enable the receiver to validate the sender's authenticity and ensure that the message was not tampered with during transit. For more information about HTTP signatures, see the IETF Draft that is maintained by the IETF HTTP Working Group.
Follow these steps to create messages using HTTP signatures:

HTTP Message Elements

An HTTP message is constructed using HTTP headers and an HTTP message body.
HTTP Message Headers
Your message header must include these HTTP header fields:
HTTP Header Fields
HTTP Header Field
Description
content-type
Also known as the Multipurpose Internet Mail Extension (MIME) type, the identifier of the media or file type resource. You can set the value to:
application/json
host
The transaction endpoint. (
api.cybersource.com
)
v-c-date
The date of the transaction in the RFC1123 format. Example:
Thu, 18 Jul 2019 00:18:03 GMT
v-c-merchant-id
Your
Cybersource
 transacting merchant ID (MID).
If you are a portfolio or merchant account user, this is the transacting merchant ID that you are sending requests on behalf of.
digest
A hash of the HTTP message body that contains your API request.
Digest is not applicable for
GET
 API requests.
signature
The digital signature, which is constructed using the values of the other headers and secured by your private key.
HTTP Message Body
Your API request.

Step 1: Set Known HTTP Header Values

Set these HTTP header values that do not require calculation:
content-type
host
v-c-date
v-c-merchant-id

Step 2: Digest Hash Calculation

The value of the
digest
 HTTP header is a hashed version of the HTTP message body that you must calculate. This hash value is used to validate the integrity of your message by the receiver.
Follow these steps to calculate the digest hash:
  1. Generate the SHA-256 hash of the JSON payload (message body).
  2. Encode the hashed string to Base64.
  3. Prepend
    SHA-256=
     to the front of the hash.
  4. Add the message body hash to the
    digest
     HTTP header field.
Creating a Message Hash Using the Command Line
shasum
 Tool
echo -n "{"clientReferenceInformation":{"code":"TC50171_3"},"paymentInformation":{"card":{"number":
				"4111111111111111","expirationMonth":"12","expirationYear":"2031"}},"orderInformation":{"amountDetails":
				{"totalAmount":"102.21","currency":"USD"},"billTo”:{“firstName":"John","lastName":"Doe","address1":
				"1MarketSt","locality":"sanfrancisco","administrativeArea":"CA","postalCode":"94105","country":"US",
				"email":"","phoneNumber":"4158880000"}}}" | shasum -a 256
echo -n "6ae5459bc8a7d6a4b203e8a734d6a616725134088e13261f5bbcefc1424fc956" | base64
Creating a Message Hash Using the Command Line
base64
 Tool
echo -n "6ae5459bc8a7d6a4b203e8a734d6a616725134088e13261f5bbcefc1424fc956" | base64
Creating a Message Hash Using C#
public static string GenerateDigest() {
				var digest = "";
				var bodyText = "{ your JSON payload }";
				using (var sha256hash = SHA256.Create()) {
				byte[] payloadBytes = sha256hash
				.ComputeHash(Encoding.UTF8.GetBytes(bodyText));
				digest = Convert.ToBase64String(payloadBytes);
				digest = "SHA-256=" + digest;
				}
				return digest;
				}
Creating a Message Using Java
public static String GenerateDigest() throws NoSuchAlgorithmException {
				String bodyText = "{ your JSON payload }";
				MessageDigest md = MessageDigest.getInstance("SHA-256");
				md.update(bodyText.getBytes(StandardCharsets.UTF_8));
				byte[] digest = md.digest();
				return "SHA-256=" + Base64.getEncoder().encodeToString(digest);
				}

Step 3: Signature Hash Calculation

Before you can construct the
signature
 HTTP header value, you must first generate the
signature hash
. To generate the signature hash value, you must use a Base64-encoded HMAC SHA-256 hash of the signature fields and their values.
This table describes the signature field values that you must use to calculate the signature hash.
Signature Fields
Signature Fields
Description
v-c-date
From the header, the date and time in the RFC1123 format.
For example:
Date: Thu, 18 Jul 2023, 22:18:03.
Digest
The Base64-encoded SHA-256 hash of the message body. For more information, see Step 2: Digest Hash Calculation.
Example:
Digest: SHA-256=gXWufV4Zc7VkN9Wkv9jh/JuAVclqDusx3vkyo3uJFWU=
Do not include the digest with GET requests.
Host
From the header, the endpoint host.
For example:
apitest.cybersource.com
.
v-c-merchant-id
From the header, the merchant ID associated with the request.
For example:
v-c-merchant-id: mymerchantid
.
request-target
The HTTP method and endpoint resource path.
For example:
request-target: post /pts/v2/payments
.
IMPORTANT
Verify that your request-target values matches exactly the resource path. For example,
/pts/v2/payments
 is not the same as
/pts/v2/payments/
.
Follow these steps to generate the signature hash value:
  1. Generate a byte array of the secret key generated previously. For more information, see Create a Shared Secret Key Pair.
  2. Generate the HMAC SHA-256 key object using the byte array of the secret key.
  3. Concatenate a string of the required information listed above.
    For more information, see
    Creating the Validation String
     below.
  4. Generate a byte array of the validation string.
  5. Use the HMAC SHA-256 key object to create the HMAC SHA-256 hash of the validation string byte array.
  6. Base64 encode the HMAC SHA-256 hash.
Signature Hash
signature=”OuKeDxj+Mg2Bh9cBnZ/25IXJs5n+qj93FvPKYpnqtTE=”

Creating the Validation String

To create the validation string, concatenate the required information in the same order as listed in the signature header field parameter. Each item must be on a separate line, and each line should be terminated with a new line character
\n
.
Validation String Example
host: 
apitest.cybersource.com
\n
date: Thu, 18 Jul 2019 00:18:03 GMT\n
request-target: post /pts/v2/payments/\n
digest: SHA-256=gXWufV4Zc7VkN9Wkv9jh/JuAVclqDusx3vkyo3uJFWU=\n
v-c-merchant-id: mymerchantid
Generating a Signature Hash in C#
private static string GenerateSignatureFromParams(string signatureParams, string secretKey) {
var sigBytes = Encoding.UTF8.GetBytes(signatureParams);
var decodedSecret = Convert.FromBase64String(secretKey);
var hmacSha256 = new HMACSHA256(decodedSecret);
var messageHash = hmacSha256.ComputeHash(sigBytes);
return Convert.ToBase64String(messageHash);
}
Generating a Signature Hash in Java
public static String GenerateSignatureFromParams(String keyString, 
String signatureParams) throws InvalidKeyException, NoSuchAlgorithmException {
byte[] decodedKey = Base64.getDecoder().decode(keyString);
SecretKey originalKey = new SecretKeySpec(decodedKey, 0, decodedKey.length, "HmacSHA256");
Mac hmacSha256 = Mac.getInstance("HmacSHA256");
hmacSha256.init(originalKey);
hmacSha256.update(signatureParams.getBytes());
byte[] HmachSha256DigestBytes = hmacSha256.doFinal();
return Base64.getEncoder().encodeToString(HmachSha256DigestBytes);}

Step 4: Constructing the Signature Header

After you generate a signature hash, you can construct the
signature
 HTTP header value.
The
signature
 HTTP header value is constructed using these parameters:
Signature Parameters
Signature Parameter
Description
keyid
The serial number of the signing certificate/key pair. Obtain this in the
Business Center
 Key Management area. For more information, see Transacting Merchant User: Create a Shared Secret Key Pair.
algorithm
The HMAC SHA256 algorithm used to encrypt the signature. It should be formatted:
HmacSHA256
.
headers
The signed-header values calculated in the signature:
  • digest
  • host
  • request-target
  • v-c-date
  • v-c-merchant-id
IMPORTANT
If you are using a meta-key, set the
v-c-merchant-id
 signature-parameter value to the meta-key creator's portfolio ID or merchant account ID. Set the
v-c-merchant-id
 HTTP header value to the transacting merchant ID (MID) that you are sending a request on-behalf of.
signature
The signature hash.
Signature Field Format
Signature:"keyid:"[keyid]",algorithm="[encryption algoritm]",headers="field1" "field2" "field3" "etc.", signature="[signature hash]"
Signature Example
Signature:"keyid="123abcki-key1-key2-key3-keyid1234567", 
algorithm="HmacSHA256", headers="host date request-target digest v-c-merchant-id", 
signature="hrptKYTtn/VfwAdUqkrQ0HT7jqAbagAbFC6nRGXrNzE="

Step 5: Complete Message with HTTP Signature

Combine all of the HTTP header values with your HTTP message body to construct your HTTP signature message.
To test your message, you can send a test request to
Cybersource
. For more information, see Test Your Set Up.
RELATED TO THIS PAGE