Generate the Header

v-c-merchant-id: mymerchantid
v-c-date: Thu, 18 Jul 2019 00:18:03 GMT
host: api.smartpayfuse-test.barclaycard 
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
v-c-date: Fri, 12 Jul 201900:44:13 GMT
host:  api.smartpayfuse-test.barclaycard
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 merchant ID.
v-c-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.smartpayfuse.barclaycard Test : api.smartpayfuse-test.barclaycard
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 `Smartpay Fuse Portal` at `https://admin.smartpayfuse.barclaycard/ebc2` in Universally Unique Identifier (UUID) format:
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

v-c-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: api.smartpayfuse-test.barclaycard
v-c-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: api.smartpayfuse-test.barclaycard
v-c-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 Smartpay Fuse Portal.

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
v-c-date: Thu, 18 Jul 2019 00:18:03 GMT
host: api.smartpayfuse-test.barclaycard 
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
v-c-date: Fri, 12 Jul 201900:44:13 GMT
host:  api.smartpayfuse-test.barclaycard
signature: keyid="6d75ffad-ed36-4a6d-85af-5609185494f4", algorithm="HmacSHA256", headers="host date (request-target) v-c-merchant-id", signature="eQkzhzu8UHEQmpBTVMibdNpPw1aLunmY41ckyLKoOjs="

Test the Message

After you construct a message header and body and determine the message’s endpoint, it is time to test your message.

Before you are ready to test your message, perform a baseline test by plugging the following test values into your client. This verifies that you are getting the associated header info as well as the same signature and digest for POST or PUT. A failure indicates a client-side problem with the logic you used to generate the header.

Because the authentication information of this baseline test is invalid, it cannot be sent. You are testing only the signature and header construction logic. However, if the values you generate for the header match the following, the construction logic is sound. You can then plug in valid information and get a successful response.

The baseline test values include only the variable data and key information.

Baseline for POST Requests

The following example provides the test values for your baseline test.

Resource: /pts/v2/payments/
Host: api.smartpayfuse-test.barclaycard
v-c-merchant-id: testmid
Date: Fri, 14 Dec 2018 00:00:00 GMT
secretKey: 0123k20MBbIB2t012345678993gHCIZsQKFpf7dR0hY=
keyID: 01234567-0123-0123-0123-012345678912
Body:
{
  "clientReferenceInformation": {
    "code": "TC50171_3"
  },
  "processingInformation": {
    "commerceIndicator": "internet"
  },
  "paymentInformation": {
    "card": {
      "number": "4111111111111111",
      "expirationMonth": "12",
      "expirationYear": "2031",
      "securityCode": "123"
    }
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "102.21",
      "currency": "USD"
    },
    "billTo": {
      "firstName": "John",
      "lastName": "Doe",
      "company": "Visa",
      "address1": "1 Market St",
      "address2": "Address 2",
      "locality": "san francisco",
      "administrativeArea": "CA",
      "postalCode": "94105",
      "country": "US",
      "email": "smartpayfusetest@barclaycard.co.uk",
      "phoneNumber": "4158880000"
    }
  }
}

The following example shows the resulting header information from your baseline test.

v-c-merchant-id: testmid
Date: Fri, 14 Dec 2018 00:00:00 GMT
Host:  api.smartpayfuse-test.barclaycard
Digest: SHA-256=a/goIo1XUCr80rnKFCWp7yRpwVL50E9RaunuEHh11XM=
Signature: keyid="01234567-0123-0123-0123-012345678912", 
algorithm="HmacSHA256", headers="host date (request-target) digest v-c-merchant-id", 
signature="SV0OVjBmO3ThK9P4CV5TaR4D/efXCVqbsE84doMdhA8="

The following example shows the signature parameter components.

host:  api.smartpayfuse-test.barclaycard
date: Fri, 14 Dec 2018 00:00:00 GMT
(request-target): post /pts/v2/payments/
digest: SHA-256=a/goIo1XUCr80rnKFCWp7yRpwVL50E9RaunuEHh11XM=
v-c-merchant-id: testmid

The following example shows the resulting endpoint.

https://api.smartpayfuse-test.barclaycard/pts/v2/payments/

Baseline for GET Requests

The following example provides the test values for your baseline test.

Resource: /tss/v2/transactions/
Host:  api.smartpayfuse-test.barclaycard
v-c-merchant-id: testmid
Date: Fri, 14 Dec 2018 00:00:00 GMT
requestID: 0123456789012345678901
secretKey: 0123k20MBbIB2t012345678993gHCIZsQKFpf7dR0hY=
keyID: 01234567-0123-0123-0123-012345678912

The following example shows the resulting header information from your baseline test.

v-c-merchant-id: testmid
Date: Fri, 14 Dec 2018 00:00:00 GMT
Host:  api.smartpayfuse-test.barclaycard
Signature: keyid="01234567-0123-0123-0123-012345678912", 
algorithm="HmacSHA256", headers="host date (request-target) v-c-merchant-id", 
signature="L7Z0LN4nP8er30DanPYNSPgZitVtCt9dubNFJhZoGHk="

The following example shows the signature parameter components.

host:  api.smartpayfuse-test.barclaycard
date: Fri, 14 Dec 2018 00:00:00 GMT
(request-target): get /tss/v2/transactions/0123456789012345678901
v-c-merchant-id: testmid

The following example shows the resulting endpoint.

https://api.smartpayfuse-test.barclaycard/tss/v2/transactions/0123456789012345678901

Generating a JSON Web Token for a GET Request

Generate the Claim Set

Use the following key:value pair.

**Claim Set Element**
Field Name	Description	Example
iat	The date and time of message origin. The date can be in any format for a time zone. This is a required field.	iat: Thur, 15 June 2017 08:12:31 GMT

Generate the Token Header

Use the following key:value pairs.

**Token Header Elements**
Field Name	Description	Example
x5c	The x5c (X.509 certificate chain) Header Parameter contains the X.509 public key certificate or certificate chain corresponding to the key(.p12) used to digitally sign the token. This is a required field.	MIICZTCCAc6gAwIBAg…Emj0F35Ew2ek4VezUXnZ/SMLvWEA6DG2sjSFCCuIot3mLJ3lI4AQSQSBSazhQec75Rk=
alg	The signing algorithm used. This is a required field.	alg: RS256
v-c-merchant-id	Merchant ID assigned in the Business Center. Required for merchant transactions. Required for partners sending transactions of behalf of merchants.	v-c-merchant-id: merchant_id

Example

{
	"x5c": "MIICZTCCAc6gAwIBAg…Emj0F35Ew2ek4VezUXnZ/SMLvWEA6DG2sjSFCCuIot3mLJ3lI4AQSQSBSazhQec75Rk=",
	"alg": "RS256",
	"v-c-merchant-id":  "merchant_id"
}

Generate the Token Signature

**Token Signature Elements**
Field Name	Description	Example
JWT Signature	Base64-encode the JWT header and the claim set created in previous steps to create the data element. Join the resulting encoded strings together with a period (.) in between them. In our pseudo code, this joined string is assigned to data. To get the JWT signature, the data string is signed with RS256 with the private key using the signing algorithm specified in the JWT header. Signature String is then encoded with Base64-encoded before creating final token.	data = base64urlEncode( JWT header ) + “.” + base64urlEncode( Claimset ) signature = RS256Hash( data, private_key ) ; signature = eyJ2LWMtbWVyY2hhbn…WYQNLMOApxv6-DdcJZK4L9mLRc3gFb1kTFvodNEI6M0GeyoFp-b9PNG32TLQITYfWmZEbTZExgQHXGwwqo

Generate the JSON Web Token

**JSON Web Token Elements**
Field Name	Description	Example
JWT Token	With All three components JWT header , claim set , and Signature , concatenate the components into a valid JWT authorization token. JWT token = JWT header.Claim set.signature Combine the header and payload and signature with periods (.) separating them.	Example: JWT Token = base64url( JWT header ) + “.” + base64url( Payload ) + “.” + base64url( Signature ) // Sample JWT header eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9 // Sample PayLoad eyJ1c2VySWQiOiJiMDhmODZhZi0zNWRhLTQ4ZjItOGZhYi1jZWYz OTA0NjYwYmQifQ // Sample signature -xN_h82PHVTCMA9vdoHrcZxH-x5mb11y1537t3rGzcM // Sample JWT Token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiJiMDhm ODZhZi0zNWRhLTQ4ZjItOGZhYi1jZWYzOTA0NjYwYmQifQ.-xN_h82PHVTCMA9vdoHrcZxH-x5mb11y1537t3rGzcM

Sample Code

Format/Example
Preparing payload: String jwtBody = "{\n \"iat\":\"" + DateTimeFormatter.RFC_1123_DATE_TIME.format(ZonedDateTime.now(ZoneId.of("GMT"))) + "\"\n} \n\n"; HashMap customHeaders = new HashMap(); customHeaders.put(v-c-merchant-id, merchantConfig.getMerchantID()); String jwsSignatureValue = sign(jwtBody, rsaPrivateKey, x509Certificate, customHeaders); Generating JWT Token—Header, Payload, and Signature: private sign(String content, PrivateKey privateKey, X509Certificate x509Certificate, Map<String, ? extends Object> customHeaders) { if(!this.isNullOrEmpty(content) && x509Certificate != null && privateKey != null) { String serialNumber = null; String serialNumberPrefix = "SERIALNUMBER="; String principal = x509Certificate.getSubjectDN().getName().toUpperCase(); int beg = principal.indexOf(serialNumberPrefix); if(beg >= 0) { int x5cBase64List = principal.indexOf(",", beg); if(x5cBase64List == -1) { x5cBase64List = principal.length(); } serialNumber = principal.substring(beg + serialNumberPrefix.length(), x5cBase64List); } else { serialNumber = x509Certificate.getSerialNumber().toString(); } ArrayList x5cBase64List1 = new ArrayList(); try { x5cBase64List1.add(Base64.encode(x509Certificate.getEncoded())); } catch (CertificateEncodingException var16) { logger.error("can\'t signAndEncrypt the payload", var16); return null; } RSAPrivateKey rsaPrivateKey = (RSAPrivateKey)privateKey; Payload payload = new Payload(content); JWSHeader jwsHeader = (new com.nimbusds.jose.JWSHeader.Builder(JWSAlgorithm.RS256)).customParams(customHeaders).keyID(serialNumber).x509CertChain(x5cBase64List1).build(); JWSObject jwsObject = new JWSObject(jwsHeader, payload); try { RSASSASigner joseException = new RSASSASigner(rsaPrivateKey); jwsObject.sign(joseException); if(!jwsObject.getState().equals(com.nimbusds.jose.JWSObject.State.SIGNED)) { logger.error("Payload signing failed."); return null; } else { return jwsObject; } } catch (JOSEException var15) { logger.error("can\'t signAndEncrypt the payload", var15); return null; } } else { logger.error("empty or null content or Private key or public certificate is null"); return null; } }

Format/Example

Preparing payload:

String jwtBody = "{\n            \"iat\":\"" +                  DateTimeFormatter.RFC_1123_DATE_TIME.format(ZonedDateTime.now(ZoneId.of("GMT"))) + "\"\n} \n\n";

HashMap customHeaders = new HashMap();
customHeaders.put(v-c-merchant-id, merchantConfig.getMerchantID());

String jwsSignatureValue = sign(jwtBody, rsaPrivateKey, x509Certificate, customHeaders);

Generating JWT Token—Header, Payload, and Signature:

private sign(String content, PrivateKey privateKey, X509Certificate x509Certificate, Map<String, ? extends Object> customHeaders) {
    if(!this.isNullOrEmpty(content) && x509Certificate != null && privateKey != null) {
        String serialNumber = null;
        String serialNumberPrefix = "SERIALNUMBER=";
        String principal = x509Certificate.getSubjectDN().getName().toUpperCase();
        int beg = principal.indexOf(serialNumberPrefix);
        if(beg >= 0) {
                int x5cBase64List = principal.indexOf(",", beg);
                if(x5cBase64List == -1) {
                    x5cBase64List = principal.length();
                }

                serialNumber = principal.substring(beg + serialNumberPrefix.length(), x5cBase64List);
        } else {
                serialNumber = x509Certificate.getSerialNumber().toString();
        }
        ArrayList x5cBase64List1 = new ArrayList();
        try {
          x5cBase64List1.add(Base64.encode(x509Certificate.getEncoded()));
        } catch (CertificateEncodingException var16) {
          logger.error("can\'t signAndEncrypt the payload", var16);
          return null;
        }

        RSAPrivateKey rsaPrivateKey = (RSAPrivateKey)privateKey;
        Payload payload = new Payload(content);
        JWSHeader jwsHeader = (new com.nimbusds.jose.JWSHeader.Builder(JWSAlgorithm.RS256)).customParams(customHeaders).keyID(serialNumber).x509CertChain(x5cBase64List1).build();
        JWSObject jwsObject = new JWSObject(jwsHeader, payload);

        try {
            RSASSASigner joseException = new RSASSASigner(rsaPrivateKey);
            jwsObject.sign(joseException);
            if(!jwsObject.getState().equals(com.nimbusds.jose.JWSObject.State.SIGNED)) {
                logger.error("Payload signing failed.");
                return null;
            } else {
                return jwsObject;
            }
        } catch (JOSEException var15) {
            logger.error("can\'t signAndEncrypt the payload", var15);
            return null;
        }
    } else {
        logger.error("empty or null content or Private key  or public certificate is null");
        return null;
    }
}

After Generating the Header

To authenticate requests, place the JSON web token in an HTTP heading in the format:

Authorization: Bearer {token string}

where the {token string} is the string without curly braces.