Exposing the Subway SubCard API

May 29, 2010

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.

Tags: , , , ,

9 Comments

  1. Faisal Ahmed says:

    Ahh, I can’t wait. Hopefully there will also be a Twitter version.

  2. [...] up on this post I finally managed to get around and finish my Facebook application, MySubs, which allows you to [...]

  3. [...] up on this post I finally managed to get around and finish my Facebook application, MySubs, which allows you to [...]

  4. dananos says:

    Hi,I’d be interested in making this into a mobile app, would you share your code?, any language is fine, just to get started.Thanks!

  5. This is a long shot but did you ever find out how they generate the code for scanning inside the app?It doesn’t look like a standard QR Code.

    • Paul says:

      Hey Matt, I just had a quick look for you and they appear to use their own QR code algorithm. The code is quite in-depth (over 200KB) so it would take some time to go through it and understand what’s going on. This map help a little; http://www.speedyshare.com/HW5NV/aztecmapsrc.bin they use it as a “type map” to generate the barcode.

      • Cheers Paul, I’ve not actually encountered .bin files before. Do they need to be extracted or can they be opened with a certain program? Cheers.

        • Paul says:

          I honestly have no idea, I’ve not done any work with QR codes before. My thinking was that maybe there was a library that accepted a “type map”, such as the bin file and then generated a QR code based on that.If you’re feeling particularly motivated grab the Android APK, decompile the source and work through the code :-) .

Leave a Comment