On This Page

REST API

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: Live : api.cybersource.com Live in India : api.in.cybersource.com Test : 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 Business Center at businesscenter.cybersource.com in Universally Unique Identifier (UUID) format: For merchants in India, the production endpoint for the Business Center is businesscenter.in.cybersource.com
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:

Convert the JSON payload (the REST body) using a SHA-256 hashing function. Compute a hash in the form of a byte array.

Generate a Base64-encoded string from the byte array.

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:

Generate a string of the Header Fields and their values.

Use one field and its value per line, and terminate all lines with

Do not use

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

Generate a byte array of the string that you created in the previous step.

Create a byte array of your decoded Secret Key that you generated in the Business Center.

Instantiate an HMACSHA256 object that is based on the decoded Secret Key byte array (from Step 3).

Use this HMACSHA256 object to compute an HMACSHA256 hash that is based on the string byte array (from Step 2).

Generate a Base64-encoded string from the byte array of the HMACSHA256 object from the previous step.

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="