Authentication

Note: For Shell you must include the following at the top of the file:

#!/bin/bash

To run this shell script, type the following chmod command and then the name of the file

chmod +x auth.sh

Example HMAC

from hashlib import sha1
import email.utils
import hmac
import requests

username = "xxxxxx-xxxx-xxxxxxxxxxxxx" # Replace with API Key from email
secret = "xxxxxx-xxxx-xxxxxxxxxxxxx" # Replace with API Secret from email
url = "xxxxxxxxxxxxxxxxxxxxxxxxx" # Replace with URL from email

dt = email.utils.formatdate(usegmt=True)
stringToSign = 'date: ' + dt;

encodedSignature = hmac.new(secret, stringToSign, sha1).digest().encode("base64").rstrip('\n')

hmacAuth = 'hmac username="' + username + '",algorithm="hmac-sha1",headers="date",signature="' + encodedSignature + '"';

headers = {
    'date': dt,
    'Authorization': hmacAuth
}

#!/bin/bash

USERNAME="xxxxxx-xxxx-xxxxxxxxxxxxx" # Replace with API Key from email
SECRET="xxxxxx-xxxx-xxxxxxxxxxxxx" # Replace with API Secret from email
URL="xxxxxxxxxxxxxxxxxxxxxxxxx" # Replace with URL from email

DATE=`date -u -R`
STRING_TO_SIGN='date: '$DATE

ENCODED_SIGNATURE=$(echo -n $STRING_TO_SIGN | openssl sha1 -binary -hmac $SECRET | base64)

HMAC_AUTH='hmac username="'$USERNAME'",algorithm="hmac-sha1",headers="date",signature="'$ENCODED_SIGNATURE'"'

var request = require('request');
var crypto = require('crypto');
var http = require("https");

var username = "xxxxxx-xxxx-xxxxxxxxxxxxx"; // Replace with API Key from email
var secret = "xxxxxx-xxxx-xxxxxxxxxxxxx"; // Replace with API Secret from email
var url = "xxxxxxxxxxxxxxxxxxxxxxxxx"; // Replace with URL from email

var getAuthenticationHeaders = function () {
  var date = new Date().toUTCString();
  var stringToSign = 'date: ' + date.trim();
  var encodedSignature = crypto.createHmac("sha1", secret).update(stringToSign).digest("base64");
  var hmacAuth = 'hmac username="' + username + '",algorithm="hmac-sha1",headers="date",signature="' + encodedSignature + '"';

  return {
    'date': date,
    'Authorization': hmacAuth
  }
}

// Required import statements
import org.apache.commons.codec.digest.HmacUtils;
import org.apache.http.HttpResponse;
import org.apache.http.Header;
import org.apache.http.message.BasicHeader;
import org.apache.http.client.HttpClient;
import org.apache.http.impl.client.HttpClientBuilder;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.util.EntityUtils;
import org.apache.http.entity.StringEntity;
import org.json.JSONObject;
import org.json.JSONArray;
import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.TimeZone;

// HMAC
public static final String username = "xxxxxx-xxxx-xxxxxxxxxxxxx"; // Replace with API Key from email
public static final String secret = "xxxxxx-xxxx-xxxxxxxxxxxxx"; // Replace with API Secret from email
public static final String apiUrl = "xxxxxxxxxxxxxxxxxxxxxxxxx"; // Replace with URL from email
public String formattedDate;
public String hmacToken;
public String authHeader;

// doGet method
private HttpResponse doGet(String uri) throws Exception {
  formattedDate = getCurrentGMTDate(); // see below for method implemetation
  hmacToken = generateHMACToken(formattedDate, secret); // see below for method implemetation
  authHeader = "hmac username=\""+username+"\", algorithm=\"hmac-sha1\", headers=\"date\", signature=\""+hmacToken+"\"";
  Header oauthHeader = new BasicHeader("authorization", authHeader );
  Header dateHeader = new BasicHeader("date", formattedDate);
  String ServiceURL = apiUrl+uri;

  HttpClient httpClientLead = HttpClientBuilder.create().build();
  HttpGet httpGet = new HttpGet(ServiceURL);
  httpGet.addHeader(oauthHeader);
  httpGet.addHeader(dateHeader);
  HttpResponse response = httpClientLead.execute(httpGet);
  return response;
}

// doPost method
private HttpResponse doPost(String uri, StringEntity payload) throws Exception {
  formattedDate = getCurrentGMTDate(); // see below for method implemetation
  hmacToken = generateHMACToken(formattedDate, secret); // see below for method implemetation
  authHeader = "hmac username=\""+username+"\", algorithm=\"hmac-sha1\", headers=\"date\", signature=\""+hmacToken+"\"";
  Header oauthHeader = new BasicHeader("authorization", authHeader );
  Header dateHeader = new BasicHeader("date", formattedDate);
  String ServiceURL = apiUrl+uri;

  HttpClient httpClientLead = HttpClientBuilder.create().build();
  HttpPost httpPost = new HttpPost(ServiceURL);
  httpPost.addHeader(oauthHeader);
  httpPost.addHeader(dateHeader);
  httpPost.addHeader("Content-Type","application/json");
  httpPost.setEntity(payload);
  HttpResponse response = httpClientLead.execute(httpPost);
  return response;
}

// method to be used in doGet and doPost methods above
public String getCurrentGMTDate(){
  Date curDate = new Date();
  SimpleDateFormat format = new SimpleDateFormat("E, dd MMM yyyy HH:mm:ss z");
  format.setTimeZone(TimeZone.getTimeZone("GMT"));
  String formattedDate = format.format(curDate);
  return formattedDate;
}

// method to be used in doGet and doPost methods above
public String generateHMACToken (String formattedDate, String secret){
  String authorizeString = org.apache.commons.codec.binary.Base64.encodeBase64String(HmacUtils.hmacSha1(secret, "date: "+formattedDate));
  return authorizeString;
}

$key = "xxxxxx-xxxx-xxxxxxxxxxxxx"; // Replace with API Secret from email
$username = "xxxxxx-xxxx-xxxxxxxxxxxxx"; // Replace with API Username from email
$url = "xxxxxxxxxxxxxxxxxxxxxxxxx"; // Replace with URL from email

$date = gmdate("r");
$stringToSign = 'date: ' . trim($date);
echo $encodedSignature = base64_encode(hash_hmac('sha1', $stringToSign, $key, true));
$hmacAuth = 'hmac username="' . $username . '",algorithm="hmac-sha1",headers="date",signature="' . $encodedSignature . '"';
return;
$headers = array(
    'date: ' . $date,
    'Authorization: ' . $hmacAuth,
);

The First Data Marketplace API requires HMAC authentication.

To try any of the code in this documentation, you can use your sandbox credentials, sent to you by email. Don’t have credentials? Request Sandbox Access

You are expected to send the following authorization headers with each API request:

Parameter	Description
username	The username of the credential received in email.
algorithm	Digital signature algorithm used to create signature. First Data supports HMAC-SHA1 & HMAC-SHA256. See detail below.
headers	List of header names, separated by a single space character, used to sign the request.
signature	Base64 encoded digital signature generated by the client.

Note: a valid time stamp (date) is mandatory for authentication.

`signature` Construction

HMAC-SHA1 is an algorithm which takes two byte-strings input: a “key” and a “message”. Use your secret (received in email) as the key, and the UTF-8 encoding of the stringToSign as the message. The output of HMAC-SHA1 is also a byte-string, called the “digest”. The signature request parameter is constructed by Base64 encoding this digest.

HMAC-SHA256 is a cryptographic hash function with 256 bits digests (hash values) computed with 32-bit and 64-bit words, respectively. To building the authentication replace SHA1 with SHA256 in your code.

HMAC Example

For an HMAC signature, the authorization header and signature are generated as follows:

Authorization: hmac username="bob", algorithm="hmac-sha1", headers="date content-md5", signature="Base64(HMAC-SHA1(stringToSign))"

The client would compose the stringToSign like this:

date: Fri, 09 Oct 2015 00:00:00 GMT\ncontent-md5: lCMsW4/JJy9vc6HjbraPzw==

Authentication

signature Construction

HMAC Example

`signature` Construction