harlantwood / aib-internet-banking-api Goto Github PK

###AIB Online Banking API I wanted to be able to access my bank account information from various sources, so I created this screenscraping API for AIB Online Banking.

This version (v2) is the newer version of AIB Online banking (2015). To use the older version, checkout branch (online-banking-v1).

###Implementation Screenscraping a banking website requires very accurate imitation of a real user using a browser. User-Agents are important. The sequence of links you navigate to get to certain information is important. Every link has a one-time-only CSRF token attached that must be used only when clicking that link.

To achieve this with the AIB Online Banking site, my strategy is to always bring the browsing session back to a "home" page and store that page HTML in a datastore (currently MapDB, for no particular reason. You can replace this with your own implementation of a StorageService if you prefer - there's a sample Cassandra implementation included too). As each API call comes through, I navigate from this known state to the pages required and then back to the home page. This makes some API calls a bit slower than you would desire, but it's easier than trying to maintain a state engine that knows where you are and how to get the desired page from there all the time.

Once you interact with the site initially it assigns a JSESSIONID cookie that must be maintained for the rest of the session. I store this in the datastore with the page contents, and create a completely independent UUID Session ID for the API to use. This keeps your actual session ID secret which is good for security reasons.

The API Session ID is returned from the first API call /v2/login/registration and must be sent as a query string parameter to all subsequent API calls. E.g.

POST /v2/login/pac?sessionId=517215a0-8c6a-11e3-97ac-001422f0bc99

All API endpoints accept Form Encoded data and return JSON.

$ curl --data "REGISTRATION_NUMBER=12345678" $API_BASE/v2/login/registration

{
    "sessionId": "517215a0-8c6a-11e3-97ac-001422f0bc99",
    "digit2": "3",
    "digit1": "2",
    "digit3": "5"
}

$ curl --data "PAC1=2&PAC2=3&PAC3=1" $API_BASE/v2/login/pac?sessionId=517215a0-8c6a-11e3-97ac-001422f0bc99

{
    "balances": 
        [{
            "id": 0,
            "name": "SAVINGS-123",
            "balance": 1085.42,
            "drcr": "",
            "transactions": null,
            "pending": false,
            "dr": false
        }]
}

The login step returns your list of accounts and their balances.

Gives the same response as Login - Step 2 above.

None

$ curl $API_BASE/v2/accounts/balances?sessionId=517215a0-8c6a-11e3-97ac-001422f0bc99

{
    "balances": 
        [{
            "id": 0,
            "name": "SAVINGS-123",
            "balance": 1085.42,
            "drcr": "",
            "transactions": null,
            "pending": false,
            "dr": false
        }]
}

Returns your list of accounts and their balances.

None

$ curl $API_BASE/v2/accounts/SAVINGS-123/transactions?sessionId=517215a0-8c6a-11e3-97ac-001422f0bc99

{
	"transactions": {
		"transactions": [
			{
				"transDate": 1379286000000,
				"narrative": "INTEREST CHARGED",
				"subNarrative": "(Incl. Surcharge- / Interest 0.00)",
				"amount": "195.86",
				"isDR": true,
				"subsequentBalance": ""
			}
		]
	}
}

Returns the list of transactions for account accountName. Not sure why it's wrapped in two transactions elements....

For accounts marked as pending in the response from /v2/accounts/balances you can retrieve all pending transactions using this endpoint.

None

$ curl $API_BASE/v2/accounts/CURRENT-123/pending?sessionId=517215a0-8c6a-11e3-97ac-001422f0bc99

[
	{
		"narrative": "MYMILKMAN", 
		"amount": "14.00",
		"account": "CURRENT-358",
		"isDR": true
	}
]

Returns the list of pending transactions for account accountName.

This is fairly experimental still - as there's a need for a digit of the PIN the first time you transfer in a session, I need all the PIN digits. Alternatively I could turn this into a two-step API call like the login...

$ curl -d "narrativeFrom=From me&narrativeTo=to you&amount=20&pinDigits=12345" \
		$API_BASE/v2/accounts/CURRENT-123/transferTo/SAVINGS-234?sessionId=517215a0-8c6a-11e3-97ac-001422f0bc99

{}

None

None

$ curl $API_BASE/v2/logout?sessionId=517215a0-8c6a-11e3-97ac-001422f0bc99

{}