Exposing the Subway SubCard API

Subway have recently brought out subcards into the UK as they was previously NI only and I had this crazy idea about making a Facebook application that would allow users to share their Subway purchases, favorite sandwiches, stores, etc. with their Facebook friends and allow them to post this information to the Live Feed.

Firstly, I needed to expose an API to latch on to so I thought I would start by decompiling their JAR file which can be used as an application on your phone and was developed by Altaine which is a New Zealand based company (which I guess explains the below .co.nz endpoints). It soon became very easy to reverse engineer as their API is HTTP based using JSON for data exchange. Instead of messing about within the Java source files I used the LG SDK to fire up an emulated phone (KP500) and launch the Subway app. Within the LG SDK it has a network sniffer so I could see exactly what was being sent and received to and from the Subways servers via the phone.

The login process is done via an HTTP POST to http://subwayeu.transactortech.co.nz/j2ee/servlet/JSONTraderEnquiry;interface=wifi and your POSTVARS must be JSON encoded as such: {“login”:”email-address-here”,”password”:”password-here”,”programID”:”6″} which is self explanatory. In all my testing programID has always been 6 for a mobile device, I assume for the official website and other future applications it will be different. interface=wifi always seems to be appended even if WiFi is off although it looks like it is optional. And yes, your password is sent in plain text.

Once we have successfully logged in the (slow) server will return us with a nice JSON string to decode, as such:

{
	"responseCode":"0", //tiny int
	"description":"OK", //string
	"traderBalances":{
		"creditBalance":"0", //tiny int
		"loyaltyBalance":"309" //tiny int
	},
	"virtualCard":"",
	"traderDetails":{
		"firstName":"", //string
		"lastName":"", //string
		"gender":"", //m or f
		"birthDate":"", //dd-mm-yyyy
		"housenumber":"", // tiny int
		"address1":"", //string
		"address2":"", //string
		"city":"", //string
		"postcode":"", //string
		"countryID":"", //tiny int
		"mobileNumber":"", //int
		"emailAddress":"", //string
		"mobCountryRegionID":"", //tiny int
		"mobCountryRegionName":"", //string
		"mailingPreferenceID":"" //tiny int
	},
	"traderLast10Transac":{
		"transaction0":{
			"date":"27-05-2010", //dd-mm-yyyy
			"merchant":"Nottingham (26587) ", //store city and store ID
			"transType":"Loyalty Allocation", //type (Loyalty Allocation, Purchase or Balance Enquiry)
			"value":0, //float
			"points":104 //int
		},
		"transaction1":{
			"date":"27-05-2010",
			"merchant":"Nottingham (26587) ",
			"transType":"Purchase",
			"value":5.29, //float (price in pounds)
			"points":0
		}
	}
}

Of which you can see returns most of the juicy information we need. I’ve tried to map out datatypes etc. (commented inline above) from what results I’ve seen but they could be wrong. For responseCode meanings see the table below.

So as you can see we have exposed a basic API that we can make usable in a basic application but their are other methods such as searchStores, searchStoresByLocation, updateDetails, notifyPassword and register but we will cover those another time.

For now I’m going to get a working application on Facebook and then maybe post some usable documentation.

Related posts:

1. MySubs – Share Subcard information with friends
2. Facebook Application – Call of Duty 5 Statistics
3. EsenAPE – send and receive SMS in real time using APE, jQuery, PHP and libape_controller