Developer Guide Menu

HTTP Signature Authentication

Authenticate CyberSource REST API requests with HTTP Signature authentication.
For code that you can use to authenticate REST API requests, see the SDK for your coding language:

Examples

These examples show the REST HTTP message header that you send to CyberSource.
REST message header for a POST or PUT request
v-c-merchant-id: mymerchantid Date: Thu, 18 Jul 2019 00:18:03 GMT Host: apitest.cybersource.com Digest: SHA-256=gXWufV4Zc7VkN9Wkv9jh/JuAVclqDusx3vkyo3uJFWU= Signature: keyid="6d75ffad-ed36-4a6d-85af-5609185494f4", algorithm="HmacSHA256", headers="host date (request-target) digest v-c-merchant-id", signature="0uKeDxj+Mg2Bh9cBnZ/25lXJs5n+qj93FvPkYpnqtTE="
REST message header for a GET request
v-c-merchant-id: mymerchantid Date: Fri, 12 Jul 201900:44:13 GMT Host: apitest.cybersource.com Signature: keyid="6d75ffad-ed36-4a6d-85af-5609185494f4", algorithm="HmacSHA256", headers="host date (request-target) v-c-merchant-id", signature="eQkzhzu8UHEQmpBTVMibdNpPw1aLunmY41ckyLKoOjs="

Header Fields

Include these fields in your REST message header.
Field
Type
Description
v-c-merchant-id
Required
Your CyberSource merchant ID.
Date
Required
The date in RFC1123 format: Thu, 18 Jul 2019 00:18:03 GMT
Host
Required
The endpoint for the transaction. Valid values:
api.cybersource.com
apitest.cybersource.com
Digest
Conditional
Do not pass this header field for GET requests. It is a hash of the JSON payload made using a SHA-256 hashing algorithm. See Generate the Digest.
Signature
Required
A comma-separated list of parameters that are formatted as name-value pairs. See Signature parameters in the table below.
Signature Parameters
Valid signature parameters:
Parameter
Description
keyid
The secret key that you create in the CyberSource Business Center at ebc2.cybersource.com in Universally Unique Identifier (UUID) format:
keyid="6d75ffad-ed36-4a6d-85af-5609185494f4"
algorithm
The encryption algorithm used to generate the signature.
Only one algorithm is supported:
algorithm="HmacSHA256"
headers
A string value of the header field names from the table above. The required header fields do not change.
POST or PUT headers:
headers="host date (request-target) digest v-c-merchant-id"
GET headers:
headers="host date (request-target) v-c-merchant-id"
signature
A Base64-encoded hash based on the name and value of each header. Each header's name and its associated value are included in a string. This string is converted to a hash value (HMACSHA256) and Base64-encoded. See Generate the signature hash.

Generate the Digest

The value that you pass in the Digest header field is a hash of your JSON payload. You create this hash using a SHA-256 hashing algorithm.
Do not send this header field with GET requests. Send it only for POST and PUT requests.
To generate the digest:
  1. Convert the JSON payload (the REST body) using a SHA-256 hashing function. Compute a hash in the form of a byte array.
  2. Generate a Base64-encoded string from the byte array.
  3. Take the Base64-encoded string and prepend
    SHA-256=
    to it.
Format for the
Digest
field:
Digest: SHA-256=gXWufV4Zc7VkN9Wkv9jh/JuAVclqDusx3vkyo3uJFWU=
Use the following code samples to verify that your code is functioning correctly. If you insert your POST or PUT body text into either of these functions, you can compare the resulting digest value to the value generated by your own application. If the values match, your digest function is working correctly.
C# Code Sample
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; }
Java Code Sample
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); }

Generate the Signature Hash

The signature hash is one of the name-value pairs or parameters that you pass within the Signature header of the REST message. It is a Base64-encoded hash of the header fields and their values. Create a string of each header field name and its associated value. Then, convert the string to a hash value (HMACSHA256) and Base64-encode it.
Example of the Signature Header Field Containing the Signature Hash
Signature: keyid="6d75ffad-ed36-4a6d-85af-5609185494f4", algorithm="HmacSHA256", headers="host date (request-target) v-c-merchant-id", signature="eQkzhzu8UHEQmpBTVMibdNpPw1aLunmY41ckyLKoOjs="
To generate a signature hash:
  1. Generate a string of the Header Fields and their values.
      • Use one field and its value per line, and terminate all lines with
        \n
      • Do not use
        \n
        at the end of the string.
      • Be sure to put the header fields in the same order as you pass them in the message header.
      • Use the same values for
        host
        ,
        date
        ,
        merchantID
        , and
        digest
        as you passed in the message header. Do not include Signature in this string.
      • Include a
        (request-target)
        field in the string.
        The
        (request-target)
        value is the HTTP verb in lowercase followed by a space, then the resource path (minus the host). The following example shows a POST request to the
        /pts/v2/payments/
        resource. Include query strings and request IDs in the request-target value.
        (request-target): post /pts/v2/payments/
      POST or PUT String Example
      host: apitest.cybersource.com date: Thu, 18 Jul 2019 00:18:03 GMT (request-target): post /pts/v2/payments/ digest: SHA-256=gXWufV4Zc7VkN9Wkv9jh/JuAVclqDusx3vkyo3uJFWU= v-c-merchant-id: mymerchantid
      GET String Example
      host: apitest.cybersource.com date: Fri, 12 Jul 2019 00:18:03 GMT (request-target): get /tss/v2/transactions/5434091601766673504001 v-c-merchant-id: mymerchantid
     
  2. Generate a byte array of the string that you created in the previous step.
  3. Create a byte array of your decoded Secret Key (which you generated in the CyberSource Business Center).
  4. Instantiate an HMACSHA256 object that is based on the decoded Secret Key byte array (from Step 3).
  5. Use this HMACSHA256 object to compute an HMACSHA256 hash that is based on the string byte array (from Step 2).
  6. Generate a Base64-encoded string from the byte array of the HMACSHA256 object from the previous step.
  7. The resulting value is the signature hash:
    signature=”OuKeDxj+Mg2Bh9cBnZ/25IXJs5n+qj93FvPKYpnqtTE=”
Sample code for generating the 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); }
Sample code for generating the 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);}
REST message header for a POST or PUT request
v-c-merchant-id: mymerchantid Date: Thu, 18 Jul 2019 00:18:03 GMT Host: apitest.cybersource.com Digest: SHA-256=gXWufV4Zc7VkN9Wkv9jh/JuAVclqDusx3vkyo3uJFWU= Signature: keyid="6d75ffad-ed36-4a6d-85af-5609185494f4", algorithm="HmacSHA256", headers="host date (request-target) digest v-c-merchant-id", signature="0uKeDxj+Mg2Bh9cBnZ/25lXJs5n+qj93FvPkYpnqtTE="
REST message header for a GET request
v-c-merchant-id: mymerchantid Date: Fri, 12 Jul 201900:44:13 GMT Host: apitest.cybersource.com Signature: keyid="6d75ffad-ed36-4a6d-85af-5609185494f4", algorithm="HmacSHA256", headers="host date (request-target) v-c-merchant-id", signature="eQkzhzu8UHEQmpBTVMibdNpPw1aLunmY41ckyLKoOjs="
Top