Introduction

This document will give you some documentation on how the BankStatements.com.au service can be integrated with your processes. Please do not hesitate to contact us if you have any questions or require any more detail or clarification.

Please visit our release notes pages for announcements about significant product releases.

Getting Started

There are three main ways that your users could interact with the BankStatements service

Being referred to our site
Through an iframe embedded on your site
Through forms on your site which connect to our API

The features available, speed of processing and cost are all the same for the three different methods. The decision on which to use could depend on the process you want your clients to follow, what internal development capabilities you have, and many other possibilities.

Referring to our Site or using the iFrame

The Referral Code

Each client organisation is issued a 4 letter Referral Code, which is used to uniquely identify your organisation. It is not case sensitive, but it is often capitalised. In this document the example referral code will be TEST.

The Referring URL

A referring URL allows you to link your users to the BankStatements.com.au site to submit their bank statements to you. The standard referring URL has the following format

https://www.bankstatements.com.au/r/b/TEST

with the TEST replaced by your referral code.

The iFrame URL

An iframe allows you to embed one website within another. Our iframe has minimal styling and little branding. It is designed to be embedded within a page on your own website. The standard iframe URL has the following format

https://www.bankstatements.com.au/iframe/start/TEST

with the TEST replaced by your referral code.

Unique Identifiers

A unique user identifier can be added to the referral code in either the referring URL or the iframe URL, usually separated by a dash. This can then be used by you and your staff or your automated systems, to connect the statements received to a specific client or application. This unique identifier is commonly numeric, but it can contain the following characters: a-z0-9~.:_-. The entire referral code should be 30 characters or smaller. To add a unique customer identifier of 845821, you could use the following URLs

Referring URL

https://www.bankstatements.com.au/r/b/TEST-845821

iFrame

https://www.bankstatements.com.au/iframe/start/TEST-845821

Additional Parameters

The following parameters can be set optionally on each url, either iframe or referring, to customise the experience for each user. They can be set either as GET parameters in the URL, or as POST parameters when loading the page. Examples in this document will use GET parameters, and will use the iframe URLs, although they work for the referring urls too. If the page is loaded as a POST request, and one of the below parameters is provided in both the POST fields and as a url/GET parameter, then the value provided in the POST field will take precedence.

BSB

A requiredBSB parameter can be set, which will then skip the Bank Selection screen for the user, and they will be taken straight to the Username/Password screen. The bsb must be exactly 6 digits long. If we cannot match the BSB to a supported bank, then the bank selection screen will be shown as normal. Example URL, with a CBA BSB number set

https://www.bankstatements.com.au/iframe/start/TEST-845821?requiredBSB=062030

ACCOUNT NUMBER

If you have one or more account numbers from the client already, and you know you will need statements from those accounts, you can set a requiredAccounts parameter. The user will then not have the option to remove those accounts from the submission. Multiple account numbers should be separated by a comma. If we cannot find an account with the specified account number, the user will be shown a warning message, but the submission will proceed normally. Example URLs with one and 3 account numbers set

https://www.bankstatements.com.au/iframe/start/TEST-845821?requiredAccounts=1234567
https://www.bankstatements.com.au/iframe/start/TEST-845821?requiredAccounts=1234567,2458965,86459

If a BSB has been set as well as one or more account numbers, then both the BSB and Account Number will need to match one of the user’s accounts for the required account to function. eg.

https://www.bankstatements.com.au/iframe/start/TEST-845821?requiredBSB=062030&requiredAccounts=1234567,2458965

This will require an account with account number 1234567 with BSB 062030 to be submitted, but an account with number 2458965 and BSB 062031 would not be required. If all account are required, then the ‘requiredAccounts’ parameter can be given a value of 'all’. In this case, the user will not be shown the accounts, and after they perform the login step, all accounts will be submitted, and the process will be complete. When combined with a requiredBSB parameter, this can make the process very short for a user.

https://www.bankstatements.com.au/iframe/start/TEST-845821?requiredAccounts=all
https://www.bankstatements.com.au/iframe/start/TEST-845821?requiredBSB=062030&requiredAccounts=all

CENTRELINK

A withCentrelink parameter can be set, to either turn the centrelink portion of the BankStatements.com.au submission process on or off. When enabled, the centrelink process is run before the bank selection and account export process. The user also has the option of skipping the centrelink section, if they do not have a centrelink online account, or have forgotten their username/password. Setting withCentrelink to 'true’, 'on’ or 'yes’ will enable the centrelink export. Setting withCentrelink to 'false’, 'off’ or 'no’ will disable the centrelink export. Omitting the withCentrelink parameter, or setting it to any other value, will use whatever the default setting for the account is.

Eg - turn it on

https://www.bankstatements.com.au/iframe/start/TEST-845821?withCentrelink=true

Eg - turn it off

https://www.bankstatements.com.au/iframe/start/TEST-845821?withCentrelink=false

There is also a centrelinkOnly parameter, to turn on or off the bank selection and submission process. If this parameter is supplied by itself with a 'true’ value then withCentrelink is also assumed to be 'true’. If this parameter is supplied along with the above withCentrelink parameter it will only set the value to 'true’ if withCentrelink has also been set to 'true’. Setting with centrelinkOnly to 'true’, 'on’ or 'yes’ will disable the bank export. Setting with centrelinkOnly to 'false’, 'off’ or 'no’ will enable the bank export. Omitting the centrelinkOnly parameter, or setting it to any other value, will use whatever the default setting for the account is.

These can of course also be combined with the other parameters.

INTEGRATION PARTNERS

Clients can authorise 3rd party applications to receive their statements. For this to occur the 3rd party (integration partner) must contact BankStatements.com.au to obtain a unique key which can be appended to the clients existing Referring URL. The key is used to either redirect the statement delivery to the integration partner or add the integration partner as an additional delivery point. Example URLs for regular and iFrame links

https://www.bankstatements.com.au/r/b/TEST?ip=D18141F5-9B5C-C45C-DB50-533CD0566582
https://www.bankstatements.com.au/iframe/start/TEST?ip=D18141F5-9B5C-C45C-DB50-533CD0566582

Javascript Loader

To ease the development required on your side in some circumstances, we have developed a javascript loader which can load the BankStatement iFrame, using parameters set in the url on your site. It provides a simple way of using different referral codes, broker codes and/or user identifiers, without having to create multiple pages on your site or within your CMS, or involving extra development work from your IT team.

EXAMPLE CODE

Please be sure to replace both instances of 'CODE’ with your unique referral code.

<div id='bankstatements' data-code='CODE'></div>
<script src='https://www.bankstatements.com.au/js/loader.js' async></script>
<noscript>
    <iframe src='https://www.bankstatements.com.au/iframe/start/CODE' style='width: 100%; height: 100%;'></iframe>
</noscript>

Include a container element with id of 'bankstatements’. It is here that the iframe will be placed. Style and size this container however you would like to. The referral code, and other attributes of the iframe can be set as 'data-frame-’ parameters in the container. The following attributes can be used. They are all optional.

This Container Attribute	Will be set as this iframe attribute
data-frame-class	class
data-frame-height	height
data-frame-sandbox	sandbox
data-frame-seamless	seamless
data-frame-srcdoc	srcdoc
data-frame-style	style
data-frame-width	width
data-frame-frameborder	frameborder

SETTING REFERRAL CODES

Rather than setting the referral code in the container, it can also be set as a URL parameter. For example, if the page where you want to host the BankStatements iframe was at http://www.example.com/statements.html, and contained code like the example above, except without a 'data-code’ attribute, then you could use the URLs http://www.example.com/statements.html?code=EXMP or http://www.example.com/statements.html?code=OTHR to use two different referral codes. Note that if a code is set via the data-code attribute of the container element, it will take precedence over the URL parameter.

BROKER CODES/SUB CODES/USER IDENTIFIERS

A broker code, or sub-account code, can also be set by using a URL parameter in the url on your site. Using the above example URL again, a broker code or user identifier could be set by using the URL http://www.example.com/statements.html?sub=DH-7543225, or to set both Referral Code and Broker Code/user identifier in the URL, then http://www.example.com/statements.html?code=EXMP&sub=DH-7543225 could be used.

SUPPORT

There may be some environments where the JS loader is unable to work properly, or does not completely fill your needs. Please contact us if you’d like to talk about adapting this for your environment or needs.

Submission of Data

The simplest and default method of submitting statements and data files is via email. To increase security and ease automation, you can also have statements and statement data submitted to a URL callback, or to an SFTP server.

DATA SUBMISSION TO URL

Please provide us with the URL where you would like us to submit the data. All data will be submitted via POST, and ideally over SSL if you support HTTPS. We will not change or add to the URL that you ask us to submit to. The URL should not perform a redirect unless it is after the data has been processed. This includes redirecting from http to https (please provide us with the https url in this case). Data will be multi-part form encoded.

Submitted Fields

The following fields will be present

Field	Desc
referrerCode	This is the complete referrer code used to initiate the process. This includes the 4-letter partner code, and any additional user identifier added to it. Together, this should be at most 25 characters. As an example, if your referrer code is 'TEST’, and you appended a customer id of '486214’ to it when loading the iframe, using the url `https://www.bankstatements.com.au/iframe/start/TEST-486214`, then this referrerCode parameter would be `TEST-486214`.
name	If the iframe has been configured to ask for the person’s full name as the first step, then this field will contain that name as entered. Otherwise, this will be an empty string. As this is entered by the user, it is not a reliable way of matching statements to a loan or application
fileCount	This contains the number of files being submitted, as an integer.
file1	The first file being submitted
file2	The second file being submitted
…	…
file{fileCount}	The final file being submitted

Files

Three different kinds of files can be submitted, depending on your requirements. They are

BankStatements.com.au generated statements These are generated and branded by us, put into a standard format for all supported banks, and (optionally) include some analysis of the statement data, including an income estimate, centrelink payments, detected loan repayments, etc. These include data up to today or yesterday, depending on the bank.
One of these files would be generated per account being submitted. They are pdfs and have a .pdf extension.
Raw Data file A JSON or XML file containing the raw data used to generate the statement above. This can also include the analysis information as described. This will have a .json or a .xml extension - you will need to tell us which format you prefer.
There will be just one file, containing the details of all accounts exported.
Bank generated eStatements These are bank branded and bank generated pdf eStatements - electronic versions of the statements that may otherwise be physically sent to the customer each month, quarter, or other regular period. The data here may be several months old, and cannot be analysed automatically by us. It is in a different format for each bank. The user must have previously registered for eStatements with their bank for us to be able to load these. We can not yet support eStatements at all banks which we otherwise support.
There may be multiple of these per account, depending on the time period you require, and the frequency that statements are issued. They are pdfs, and have a .pdf extension. To differentiate them from our statements, the filename ends with “-e.pdf”.

Equivalent Submission Form

The data as described above will be submitted in the same way as if the following form were submitted

<form method='POST' enctype='multipart/form-data' action='https://YOUR_URL.COM/SUBMIT/HERE'>
    <input name='referrerCode' type='text' />
    <input name='name' type='text' />
    <input name='fileCount' type='text' />
    <input name='file1' type='file' />
    <input name='file2' type='file' />
    <input name='file3' type='file' />
    ...
</form>

SFTP UPLOAD

If you would like to have files sent to an SFTP server, please provide us with the host, port number and desired upload directory, along with a valid user credentials for an account which has write permissions. We will upload all relevant export files at the specified path.

PGP Encryption

We support encryption of generated reports using the Open PGP standard. Please provide us with your PGP Public Key, and we will encrypt all files which we submit to you with that key. We are not currently signing the PGP encrypted files. This can be enabled for any submission method (email, SFTP, URL Callback). We recommend thoroughly testing your processes in our test environment before enabling this in a production environment.

Returning Control

To provide clients with more complete control over the user experience, once a user has completed the statement submission process, we can redirect them to another page on your site. The redirect target URL is stored as a part of your client record on our end.

WHEN WILL A USER BE REDIRECTED

A user will be redirected once the statement submission process has been completed. This could be a successful completion or an unsuccessful completion. Unsuccessful finishes could be because the user entered the wrong credentials two or more times, or because of one of a number of other errors that occur from time to time. We will attempt to perform the redirect on the outermost parent page available (the javascript top page). In the case that this fails, then just the iframe itself will be redirected. It is not expected that the top redirect will fail, but the backup is in place, in case there is a change to browser security models or other similar features.

PARAMETERS

The following parameters will be passed in the URL

referrerCode - The complete referrer code as set in the iframe URL, including 4 letter client code and any unique client identifier.
status - One of the following three statuses
- COMPLETE - The process completed successfully
- LOGIN_FAIL - The user has submitted incorrect credentials two or more times
- ERROR - An error occurred

If the status is error, then the following two parameters will also be provided

errorCode - This is normally a 5 digit number. Details of these will be included in this document at a later date.
errorText - This is a text message suitable to show a user about what error has occurred.

The API

BankStatements exposes its functionality via an Application Programming Interface (API) in order to support the development of third party applications that can integrate directly with the BankStatements service. This will allows you to build a customised user interface and experience with which your customers can interact with BankStatements. This can enable you to integrate the bank statement retrieval process seamlessly into the normal flow of your user acquisition or sign-up process.

This section describes how to integrate with the BankStatements API.

Getting Started with the API

In order to interact with the BankStatements API you will need to:

Determine the base API URL for your API requests.
Obtain an API Key specific to the API environment you will be using.
Determine the data format that you will use to send API requests, and the data format you will use when receiving API responses.
Begin testing your application’s integration with the API.

API URL

The BankStatements API is available via a production environment (i.e https://www.bankstatements.com.au/api/v1/) and a test environment (i.e. https://test.bankstatements.com.au/api/v1/). All API calls must include the API version as the first part of the URL’s path, and this then forms the base URL. For example:

https://www.bankstatements.com.au/api/v1/
https://test.bankstatements.com.au/api/v1/

The request endpoints for API functions that are specified in this document are relative to these base urls.

API Versions

The API is versioned, so that changes and updates to the API do not cause compatibility issues with existing integrations. The API version is determined by the number in the API URL. The current version is v1.

Backwards compatible changes to the API may be introduced to an API version over time, such as adding new endpoints or optional fields to existing endpoints etc. These changes will be announced and documented in order to allow existing clients to be able to take advantage of newer API functionality.

It is possible to interact with specific versions of API functions by using the custom HTTP header X-OUTPUT-VERSION, which requires a value of a date in the format yyyymmdd (i.e. 20160527). This allows integration with a specific version of an API function. When this HTTP header is not provided, then the base API function will be used as a default. This means that newer functionality and/or response formats must be explicitly requested.

Currently available version values are as follows

Version String	Description	Details
<blank>	The original version.	Details
`20160527`	Simplifies and standardises the raw data format. A complete re-write from the original version.	Details
`20170401`	A minor update from the previous version. Makes Analysis Points more consistent, and allows for Decision Metrics which provide key metrics across all accounts.	Details
`20190901`	This version allows multiple accounts from multiple banks to be present together in a single statement. There were some additional changes to the individual bank statement sections to improve consistency between the json and xml formats.	Details

API Keys

All requests to the API must include your API key. This can be included either as a custom HTTP header X-API-KEY, or as a GET/POST variable (also named X-API-KEY). Please send us an email when you need your key, and we will provide it to you. We can also expire old keys if they are no longer needed, and generate new keys if requested. Keys will also be different in test and production environments.

API Data Formats

The API currently supports receiving and providing data in one of multiple data formats. Each request that your application sends to the API should include a HTTP header to communicate the format of the data that is being sent, and also to specify the format of the data that should be returned. Note that while there is a default data format that will be used if the associated HTTP header is omitted, it is recommended that your application is explicit in defining the data formats that it requires.

This document provides examples of the API requests and responses in all of the available data formats.

Request Data Format

For API functions that require input data, the data sent to the API should match the request type part of the API function. For example, if the request type is GET then any required data would be provided as query string variables, and if the request type is POST then the required data would be provided as part of the request body.

When data is sent in the request body, the request MUST include a Content-Type HTTP header that specifies the format of the provided body content. If the Content-Type HTTP header is omitted from a request that contains body content then the request will be rejected and an error response provided.

The following content types are supported, with their corresponding Content-Type values:

Data Format	HTTP header	Value
JSON	`Content-Type`	`application/json`
XML	`Content-Type`	`application/xml`

All API calls should include the Content-Type otherwise the request will be rejected. If a body is included with the request, then the body must contain correctly formatted content of the specified content type, otherwise the request will be rejected.

Response Data Format

Data returned from the API to your application can be sent in one of the following formats. In order to inform the API of the desired format of the data being returned from the request, it is necessary to include an Accept HTTP header with the desired value. If the Accept HTTP header is omitted then the API will provide the response in JSON format.

Data Format	HTTP header	Value
JSON	Accept:	application/json
XML	Accept	application/xml

In addition to the returned data, all successful responses will include a user_token field. This user token will be required for further calls to the API in relation to the same user.

The Accept HTTP header should always be provided, even if the API function will typically return some other content type (i.e. such as the Retrieve Files request). This will ensure that if an error occurs, the error message will be returned in the format you require.

User Token

As mentioned in Response Data Format, all successful responses will include a user_token field. This is a temporary, unique session ID that must be included in subsequent requests relating to an individual user and the data session.

The user_token may change with subsequent requests, so care should be taken to use the most recently provided token. The token can be provided either as a POST/GET parameter called user_token. Alternately, the token can be set in an HTTP header called X-USER-TOKEN. If specified in both places, then the GET or POST variable will be used.

Customer Referral/Reference Code

If you have an internal reference for a customer, it is recommended to add this with your API requests. This will allow us to better debug any issues that may happen to arise. If you are loading pdf statements, then this value will be included in the statement, which may be helpful for relating statements to a customer.

See Unique Identifiers for more details on the limitations of this field.

The referral code only needs to be included in one request for each session - Login or Login and Fetch All Statements probably make the most sense. See Setting Referral Codes for additional information when using with the Javascript Loader.

It may also be set as an HTTP header called REFERRAL-CODE (case not significant).

As used in the API, the referral_code does not strictly need to begin with your 4 letter client code.

Testing

Testing of your application’s integration with BankStatements should be performed in the test API environment (see API URLs).

To assist with testing, BankStatements provides some example customer credentials and institutions that can be used, so that it is not necessary to perform the initial testing with real customer credentials. This can assist in avoiding any temporary lockouts that could otherwise occur if the customer credential data is incorrectly submitted. These testing credentials will only work in the test environment.

Once you have confirmed that your application is able to work correctly with the test credentials, you will want to test with real customer credentials, and then contact us to obtain an API Key for the production environment.

Basic Test Account Details

Example Basic Login Request:

{
    "credentials": {
        "institution": "bank_of_statements",
        "username": "12345678",
        "password": "TestMyMoney"
    }
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <credentials>
    <institution>bank_of_statements</institution>
    <username>12345678</username>
    <password>TestMyMoney</password>
  </credentials>
</xml>

A bank has been set up in the test environment called “Bank of Statements” that can be used in related API functions (such as the Login request). It will allow you to test the basic/standard scenarios of the API functions (i.e. without any MFA steps). If you change the username of password then the response will be an error message.

Credential Name	Value
`institution`	`bank_of_statements`
`username`	`12345678`
`password`	`TestMyMoney`

These credentials provide access to two accounts, which will remain constant. Transaction data will be randomly generated for each request, and will be internally consistent - i.e. the total credits and debits, as well as the running balance, will be correct for the data provided.

MFA Test Account Details

Some institutions use MFA when authenticating user credentials. A bank has been set up in the test environment called “Bank of MFA” that can be used when authenticating with BankStatements. It will allow you to test the basic/standard scenarios of the API functions (such as the Login request), with the addition of MFA steps. This will allow you to replicate the MFA request/response process that is used by various institutions.

Credential Name	Value
`institution`	`bank_of_mfa`

The credentials below can be used to simulate different types of MFA, per the descriptions. For each test account described, a credential named with-mfa should be supplied with the value of with. This will enable the MFA functionality and cause a MFA Request to be returned. For any other value, MFA will not be used. Please refer to Additional MFA Request Examples for more detail on the actual requests that can be received.

AVAILABLE CREDENTIALS

A single text field, entering a code from a token

Example CBA Login Request:

{
    "credentials": {
        "institution": "bank_of_mfa",
        "username": "cba",
        "password": "cba",
        "with-mfa": "with"
    }
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <credentials>
    <institution>bank_of_mfa</institution>
    <username>cba</username>
    <password>cba</password>
    <with-mfa>with</with-mfa>
  </credentials>
</xml>

Example CBA MFA Response:

{
  "user_token": "ttqmm051fti9hbvimpkv9c8q07",
  "netcode": "123456"
}

<xml>
  <user_token>ttqmm051fti9hbvimpkv9c8q07</user_token>
  <netcode>123456</netcode>
</xml>

Credential Name	Value
`username`	`cba`
`password`	`cba`
`with-mfa`	`with`

The MFA Response will require the following data to be submitted.

MFA Response	Test Value
`netcode`	`123456`

Selecting between a set of account profiles

Example Westpac Login Request:

{
    "credentials": {
        "institution": "bank_of_mfa",
        "username": "westpac",
        "password": "westpac",
        "with-mfa": "with"
    }
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <credentials>
    <institution>bank_of_mfa</institution>
    <username>westpac</username>
    <password>westpac</password>
    <with-mfa>with</with-mfa>
  </credentials>
</xml>

Example Westpac MFA Response:

{
  "user_token": "ttqmm051fti9hbvimpkv9c8q07",
  "profile": "1234"
}

<xml>
  <user_token>ttqmm051fti9hbvimpkv9c8q07</user_token>
  <profile>1234</profile>
</xml>

Credential Name	Value
`username`	`westpac`
`password`	`westpac`
`with-mfa`	`with`

The MFA Response will require one of the following data to be submitted.

MFA Response	Test Value
`profile`	`1234`

profile 5678

Two text fields - entering a password and a value from a token

Credential Name	Value
`username`	`hsbc-device`
`password`	`hsbc-device`
`with-mfa`	`with`

The MFA Response will require the following data to be submitted.

MFA Response	Test Value
`memorableAnswer`	`12345678`
`idv_OtpCredential`	`987654`

Entering a password, and then three select characters from a secondary password

Example HSBC-Passwords Login Request:

{
    "credentials": {
        "institution": "bank_of_mfa",
        "username": "hsbc-passwords",
        "password": "hsbc-passwords",
        "with-mfa": "with"
    }
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <credentials>
    <institution>bank_of_mfa</institution>
    <username>hsbc-passwords</username>
    <password>hsbc-passwords</password>
    <with-mfa>with</with-mfa>
  </credentials>
</xml>

Example HSBC-Passwords MFA Response:

{
  "user_token": "ttqmm051fti9hbvimpkv9c8q07",
  "memorableAnswer": "12345678",
  "RCCField0": "Q",
  "RCCField2": "E",
  "RCCField5": "Y"
}

<xml>
  <user_token>ttqmm051fti9hbvimpkv9c8q07</user_token>
  <memorableAnswer>12345678</memorableAnswer>
  <RCCField0>Q</RCCField0>
  <RCCField2>E</RCCField2>
  <RCCField5>Y</RCCField5>
</xml>

Credential Name	Value
`username`	`hsbc-passwords`
`password`	`hsbc-passwords`
`with-mfa`	`with`

The MFA Response will require the following data to be submitted.

MFA Response	Test Value
`memorableAnswer`	`12345678`
`RCCField0`*	`Q`
`RCCField2`*	`E`
`RCCField5`*	`Y`
	* Note that the `RCCFieldX` elements that must be submitted will be different for each request, and they will correspond to one of the letters from the Secondary Password (which for this test account is `QWERTYUI`). The value to submit will be the corresponding letter from the Secondary Password.

Entering a password, and then enter code from digipass device (rabobank)

Example Rabobank Login Request:

{
    "credentials": {
        "institution": "bank_of_mfa",
        "username": "rabo",
        "password": "rabo",
        "with-mfa": "with"
    }
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <credentials>
    <institution>bank_of_mfa</institution>
    <username>rabo</username>
    <password>rabo</password>
    <with-mfa>with</with-mfa>
  </credentials>
</xml>

Example Rabobank MFA Response:

{
  "user_token": "ttqmm051fti9hbvimpkv9c8q07",
  "password": "98765"
}

<xml>
  <user_token>ttqmm051fti9hbvimpkv9c8q07</user_token>
  <password>98765</password>
</xml>

Credential Name	Value
`username`	`rabo`
`password`	`rabo`
`with-mfa`	`with`

The MFA Response will require the following data to be submitted.

MFA Response	Test Value
`password`	`98765`
	The value to submit will come from digipass device.

Entering a username and then enter MFA (rabobank) (without password)

Example Rabobank Login Request:

{
    "credentials": {
        "institution": "bank_of_mfa",
        "username": "rabo",
        "with-mfa": "with"
    }
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <credentials>
    <institution>bank_of_mfa</institution>
    <username>rabo</username>
    <with-mfa>with</with-mfa>
  </credentials>
</xml>

Example Rabobank MFA Response:

{
    "mfa": {
        "title": "Login to Internet Banking with Digipass",
        "fields": [
            {
                "type": "header",
                "value": "Please Enter Your Digipass (98765)"
            },
            {
                "type": "set",
                "subElements": [
                    {
                        "type": "instructions",
                        "value": "Start the Digipass by pressing the orange key"
                    },
                    {
                        "type": "instructions",
                        "value": "Enter your 5 digit PIN."
                    },
                    {
                        "type": "instructions",
                        "value": "'APPLI' will display. Press 1"
                    },
                    {
                        "type": "instructions",
                        "value": "Digipass will generate a code. Please enter this code to login."
                    }
                ]
            },
            {
                "type": "password",
                "id": "password",
                "label": "Enter Digipass code"
            }
        ]
    },
    "user_token": "o8ksvi7o6vhdlfrvfharg4r80m"
}

<xml>
  <user_token>o8ksvi7o6vhdlfrvfharg4r80m</user_token>
  <password>98765</password>
</xml>

Credential Name	Value
`username`	`rabo`
`with-mfa`	`with`

The MFA Response will require the following data to be submitted.

MFA Response	Test Value
`password`	`98765`
	The value to submit will come from digipass device.

MFA response with HTML hidden field for Push Notification

Example Request for Bendigo Push Notification:

{
    "credentials": {
        "institution": "bank_of_mfa",
        "username": "bendigo",
        "password": "bendigo",
        "with-mfa": "with"
    }
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <credentials>
    <institution>bank_of_mfa</institution>
    <username>bendigo</username>
    <password>bendigo</password>
    <with-mfa>with</with-mfa>
  </credentials>
</xml>

Credential Name	Value
`username`	`bendigo`
`password`	`bendigo`
`with-mfa`	`with`

The MFA Response will require the following data to be submitted.

MFA Response	Test Value
`is_push`	yes
	* Note that in a real scenario we use is_push as a flag to monitor the response from API. Once we get correct response from the API we send the value `yes` to the flag to denote user have successfully verified push notification.
`generatePushAgain`	yes
	*[OPTIONAL] In case of time out of initial request, `generatePushAgain` can be sent with value `yes` to request the push notification again.

Example Response for Bendigo Push Notification:

{
    "mfa": {
        "title": "",
        "fields": [
            {
                "type": "header",
                "value": "Open the Bendigo Bank app",
                "htmlAttrs": {}
            },
            {
                "type": "instructions",
                "value": "We’ve sent a notification to your device from the Bendigo Bank app to confirm it’s really you. \r\n\n\n Tap the notification or open the app, and choose `Yes, that’s me` to finish logging in.",
                "htmlAttrs": {}
            },
            {
                "type": "hidden",
                "id": "is_push",
                "htmlAttrs": {
                    "value": "yes"
                }
            }
        ]
    },
    "user_token": "6v4aumgs.........moe9fhmdl",
    "referral_code": "MfaTestBendigo11"
}

<?xml version="1.0" encoding="utf-8"?>
<xml dataVersion="20170401">
    <mfa>
        <title/>
        <fields>
            <field>
                <type>header</type>
                <value>Open the Bendigo Bank app</value>
                <htmlAttrs/>
            </field>
            <field>
                <type>instructions</type>
                <value>We’ve sent a notification to your device from the Bendigo Bank app to confirm it’s really you. &#13; Tap the notification or open the app, and choose `Yes, that’s me` to finish logging in.</value>
                <htmlAttrs/>
            </field>
            <field>
                <type>hidden</type>
                <id>is_push</id>
                <htmlAttrs>
                    <value>yes</value>
                </htmlAttrs>
            </field>
        </fields>
    </mfa>
    <user_token>6v4aumgs.........moe9fhmdl</user_token>
    <referral_code>MfaTestBendigo11</referral_code>
</xml>

Example Response for Bendigo Push Notification (in timeout case):

{
    "mfa": {
        "title": "",
        "fields": [
            {
                "type": "header",
                "value": "Security request timed out",
                "htmlAttrs": {}
            },
            {
                "type": "instructions",
                "value": "Sorry, your request has timed out. If you like you can try again by sending another notification to your device using button below to confirm it’s really you. Then tap the notification or open the app, and choose `Yes, that’s me` to finish logging in.",
                "htmlAttrs": {}
            },
            {
                "type": "hidden",
                "id": "is_push",
                "htmlAttrs": {
                    "value": "yes"
                }
            },
            {
                "type": "hidden",
                "id": "generatePushAgain",
                "htmlAttrs": {
                    "value": "yes"
                }
            }
        ]
    },
    "user_token": "6v4aumgs.........moe9fhmdl",
    "referral_code": "MfaTestBendigo11"
}

<?xml version="1.0" encoding="utf-8"?>
<xml dataVersion="20170401">
    <mfa>
        <title/>
        <fields>
            <field>
                <type>header</type>
                <value>Security request timed out</value>
                <htmlAttrs/>
            </field>
            <field>
                <type>instructions</type>
                <value>Sorry, your request has timed out. If you like you can try again by sending another notification to your device using button below to confirm it’s really you. Then tap the notification or open the app, and choose `Yes, that’s me` to finish logging in.</value>
                <htmlAttrs/>
            </field>
            <field>
                <type>hidden</type>
                <id>is_push</id>
                <htmlAttrs>
                    <value>yes</value>
                </htmlAttrs>
            </field>
            <field>
                <type>hidden</type>
                <id>generatePushAgain</id>
                <htmlAttrs>
                    <value>yes</value>
                </htmlAttrs>
            </field>
        </fields>
    </mfa>
    <user_token>6v4aumgs.........moe9fhmdl</user_token>
    <referral_code>MfaTestBendigo11</referral_code>
</xml>

Example Request for Macquarie Push Notification:

{
    "credentials": {
        "institution": "bank_of_mfa",
        "username": "macquarie",
        "password": "macquarie",
        "with-mfa": "with"
    }
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <credentials>
    <institution>bank_of_mfa</institution>
    <username>macquarie</username>
    <password>macquarie</password>
    <with-mfa>with</with-mfa>
  </credentials>
</xml>

Credential Name	Value
`username`	`macquarie`
`password`	`macquarie`
`with-mfa`	`with`

The MFA Response will require the following data to be submitted.

MFA Response	Test Value
`is_push`	yes
	* Note that in a real scenario we use is_push as a flag to monitor the response from API. Once we get correct response from the API we send the value `yes` to the flag to denote user have successfully verified push notification.

Example Response for Macquarie Push Notification:

{
    "mfa": {
        "title": "",
        "fields": [
            {
                "type": "header",
                "value": "Verification required: Security step-up",
                "htmlAttrs": {}
            },
            {
                "type": "instructions",
                "value": "We are now verifying your logins as a result of you updating your security level.\r\n        A push notification has been sent to your registered device for verification.\r\n        Please confirm the verification steps on your device prior to proceeding with this process",
                "htmlAttrs": {}
            },
            {
                "type": "hidden",
                "id": "is_push",
                "htmlAttrs": {
                    "value": "yes"
                }
            }
        ]
    },
    "user_token": "6v4aumgs.........moe9fhmdl",
    "referral_code": "MfaTestMacquarie11"
}

<?xml version="1.0" encoding="utf-8"?>
<xml dataVersion="20170401">
    <mfa>
        <title/>
        <fields>
            <field>
                <type>header</type>
                <value>Verification required: Security step-up</value>
                <htmlAttrs/>
            </field>
            <field>
                <type>instructions</type>
                <value>We are now verifying your logins as a result of you updating your security level.&#13;
        A push notification has been sent to your registered device for verification.&#13;
        Please confirm the verification steps on your device prior to proceeding with this process</value>
                <htmlAttrs/>
            </field>
            <field>
                <type>hidden</type>
                <id>is_push</id>
                <htmlAttrs>
                    <value>yes</value>
                </htmlAttrs>
            </field>
        </fields>
    </mfa>
    <user_token>6v4aumgs.........moe9fhmdl</user_token>
    <referral_code>MfaTestMacquarie11</referral_code>
</xml>

MFA response with HTML hidden field

Example Request for HTML with hidden Field:

{
    "credentials": {
        "institution": "bank_of_mfa",
        "username": "mfaExampleHtmlHidden",
        "password": "mfaExampleHtmlHidden",
        "with-mfa": "with"
    }
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <credentials>
    <institution>bank_of_mfa</institution>
    <username>mfaExampleHtmlHidden</username>
    <password>mfaExampleHtmlHidden</password>
    <with-mfa>with</with-mfa>
  </credentials>
</xml>

Example Response for HTML with hidden Field:

{
    "user_token": "vg21q0icdkeen3l0k6sudhr79n",
    "sequence": "78"
}

<xml>
   <user_token>vg21q0icdkeen3l0k6sudhr79n</user_token>
   <sequence>78</sequence>
</xml>

Credential Name	Value
`username`	`mfaExampleHtmlHidden`
`password`	`mfaExampleHtmlHidden`
`with-mfa`	`with`

The MFA Response will require the following data to be submitted.

MFA Response	Test Value
`sequence`	`78`
	* Note that in a real scenario the hidden name and value will be different, depending on the actual bank. The hidden value provided in the MFA request should be returned in the MFA Response.

MFA response with button

Example Request for button type:

{
    "credentials": {
        "institution": "bank_of_mfa",
        "username": "mfaExampleButton",
        "password": "mfaExampleButton",
        "with-mfa": "with"
    }
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <credentials>
    <institution>bank_of_mfa</institution>
    <username>mfaExampleButton</username>
    <password>mfaExampleButton</password>
    <with-mfa>with</with-mfa>
  </credentials>
</xml>

Example Response for button type:

{
    "user_token": "vg21q0icdkeen3l0k6sudhr79n",
    "button_clicked": "1"
}

<xml>
   <user_token>vg21q0icdkeen3l0k6sudhr79n</user_token>
   <button_clicked>1</button_clicked>
</xml>

Credential Name	Value
`username`	`mfaExampleButton`
`password`	`mfaExampleButton`
`with-mfa`	`with`

The MFA Response will require the following action.

MFA Response	Test Value
	* Note that this is an example of a button that when it is clicked via a UI, it will update the value on a hidden type. The MFA login is actually validating the value for the ‘button_clicked’ field, which needs to be updated via the button click. This is a different scenario from the preceeding example, because the JavaScript will change the hidden value.

MFA response with image

Example Request for image type:

{
    "credentials": {
        "institution": "bank_of_mfa",
        "username": "mfaExampleImage",
        "password": "mfaExampleImage",
        "with-mfa": "with"
    }
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <credentials>
    <institution>bank_of_mfa</institution>
    <username>mfaExampleImage</username>
    <password>mfaExampleImage</password>
    <with-mfa>with</with-mfa>
  </credentials>
</xml>

Example Response for image type:

{
    "user_token": "vg21q0icdkeen3l0k6sudhr79n",
    "captcha_value": "D49ZHN"
}

<xml>
   <user_token>vg21q0icdkeen3l0k6sudhr79n</user_token>
   <captcha_value>D49ZHN</captcha_value>
</xml>

Credential Name	Value
`username`	`mfaExampleImage`
`password`	`mfaExampleImage`
`with-mfa`	`with`

The MFA Response will require the following action.

MFA Response	Test Value
	* The MFA Request will contain a base64 encoded image. In this example, the image is a captcha image with the letters that must be included in the input field. The value for this example is `D49ZHN`.

MFA response with options

Example Request for options type:

{
    "credentials": {
        "institution": "bank_of_mfa",
        "username": "mfaExampleOptions",
        "password": "mfaExampleOptions",
        "with-mfa": "with"
    }
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <credentials>
    <institution>bank_of_mfa</institution>
    <username>mfaExampleOptions</username>
    <password>mfaExampleOptions</password>
    <with-mfa>with</with-mfa>
  </credentials>
</xml>

Example Response for options type:

{
    "user_token": "vg21q0icdkeen3l0k6sudhr79n",
    "profile": "1234"
}

<xml>
   <user_token>vg21q0icdkeen3l0k6sudhr79n</user_token>
   <profile>1234</profile>
</xml>

Credential Name	Value
`username`	`mfaExampleOptions`
`password`	`mfaExampleOptions`
`with-mfa`	`with`

The MFA Response will require the following action.

MFA Response	Test Value
	* There are two valid values that can be provided in the MFA Response for this example, either `1234` or `5678`.

MFA response for multiple step MFA with profile selection

Example Request for multiple step MFA with profile selection:

{
    "credentials": {
        "institution": "bank_of_mfa",
        "username": "mfaAndProfile",
        "password": "mfaAndProfile",
        "with-mfa": "with"
    }
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <credentials>
    <institution>bank_of_mfa</institution>
    <username>mfaAndProfile</username>
    <password>mfaAndProfile</password>
    <with-mfa>with</with-mfa>
  </credentials>
</xml>

Example Response for multiple step MFA with profile selection:

{
    "user_token": "vg21q0icdkeen3l0k6sudhr79n",
    "netcode": "123456",
    "profile": "1234"
}

<xml>
   <user_token>vg21q0icdkeen3l0k6sudhr79n</user_token>
   <netcode>123456</profile>
   <profile>1234</profile>
</xml>

Credential Name	Value
`username`	`mfaAndProfile`
`password`	`mfaAndProfile`
`with-mfa`	`with`

The MFA Response will require the following action.

MFA Response	Test Value
MFA`netcode`	`123456`
Profile selection`profile`	`1234`

Optional MFA Test Account Details

There are a few banks where some users may be required to enter a value from an MFA device together with their other credentials (username and password), rather than on a second form as is the case for the MFA described above. We have a separate test bank available to test this, the Bank of Optional MFA.

Bank Name	Bank Slug
`Bank of Optional MFA`	`bank_of_optmfa`

Two sets of credentials are available for this bank - one which requires the MFA value, and one which must not be used with an mfa value.

Credential Name	Value
`username`	`with`
`password`	`with`
`date (MFA field)`	`Today's date in Ymd format. Eg 20170718`

Credential Name	Value
`username`	`without`
`password`	`without`
`date (MFA field)`	`<blank>`

Captcha Test Account Details

Example Captcha Login Preload Request:

{
  "institution": "bank_of_captcha"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <institution>bank_of_captcha</institution>
</xml>

Example Captcha Login Request:

{
    "credentials": {
        "institution": "bank_of_captcha",
        "username": "12345678",
        "password": "TestMyMoney",
        "captcha": "D49ZHN"
    }
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <credentials>
    <institution>bank_of_captcha</institution>
    <username>12345678</username>
    <password>TestMyMoney</password>
    <captcha>D49ZHN</captcha>
  </credentials>
</xml>

Some institutions require the user to respond to a CAPTCHA before finalising the log in process. This is a variation of the MFA process, in that the bank will return a response containing typically a base64 encoded image. A bank has been set up in the test environment called “Bank of CAPTCHA” that can be used when creating customers in BankStatements, in order to test this scenario with the API functions.

Note that this will require a Preload Login request before attempting the Login request. The Preload request will contain the base64 encoded image with the letters that must be included in the Login Request.

Credential Name	Value
`institution`	`bank_of_captcha`
`username`	`12345678`
`password`	`TestMyMoney`
`captcha`	`D49ZHN`

Mortgage Test Account Details

Example Login Request:

{
    "credentials": {
        "institution": "bank_of_mortgage",
        "username": "12345678",
        "password": "TestMyMoney"
    }
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <credentials>
    <institution>bank_of_mortgage</institution>
    <username>12345678</username>
    <password>TestMyMoney</password>
  </credentials>
</xml>

A bank has been set up in the test environment called “Bank of Mortgage” that can be used in related API functions (such as the Login request). It is similar to the test bank described in the Basic Test Account Details however it differs in that it contains examples of mortgage accounts. There are several different logins that can be used to retrieve different profiles of data.

Credential Name	Value
`institution`	`bank_of_mortgage`
`username`	`12345678`
`password`	`TestMyMoney`

`institution`	`bank_of_mortgage`
`username`	`7777`
`password`	`weekly`

`institution`	`bank_of_mortgage`
`username`	`1414`
`password`	`fortnightly`

`institution`	`bank_of_mortgage`
`username`	`3031`
`password`	`monthly`

Testing Error Conditions

Example Basic Login Request (which will trigger an error on export):

{
    "credentials": {
        "institution": "bank_of_statements",
        "username": "error",
        "password": "error"
    }
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <credentials>
    <institution>bank_of_statements</institution>
    <username>error</username>
    <password>error</password>
  </credentials>
</xml>

A special credential pair has been set up with Bank of Statements to test errors that occur after a successful login. Using the credentials below, login will be successful, but any attempt to export transactions will cause an error.

Credential Name	Value
`institution`	`bank_of_statements`
`username`	`error`
`password`	`error`

Using the credentials below, login wil trigger MB_EXCEPTION_USER_ACTION_REQUIRED(30004) error.

Credential Name	Value
`institution`	`bank_of_statements`
`username`	`error`
`password`	`30004`

API Functions

This section describes the available functions provided by the BankStatements API.

Verify API Status

Response:

{
  "status": true
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <status>1</status>
</xml>

DESCRIPTION

Checks if the API is online and functioning.

FUNCTION

Request Part	Value
`Type`	GET
`URL`	/verify

REQUEST HEADER

Name	Required	Value
`X-API-KEY`		Your API key (see API Keys)
`Content-Type`		The data format of your request (see Request Data Format)
`Accept`		The desired data format of the response (see Response Data Format)

RETURN RESPONSE

Will return status of true if the API is online and working. Any other response indicate’s that the API is offline (i.e. if you receive a network timeout error, or other connectivity error).

List Institutions

Response:

{
  "institutions":
  [
    {
      "slug": "anz",
      "name": "ANZ",
      "credentials":
      [
        {
          "name": "Customer Registration Number",
          "fieldID": "username",
          "type": "TEXT",
          "description": "",
          "values": "",
          "keyboardType": "number"
        },
        {
          "name": "Password",
          "fieldID": "password",
          "type": "password",
          "description": "",
          "values": "",
          "keyboardType": "default"
        }
      ],
      "status": "",
      "searchable": "1",
      "display": "1",
      "searchVal": "anzaustralianewzealandaustraliaandnewzealandbankinggroup",
      "region": "au",
      "export_with_password": 0,
      "estatements_supported": 1,
      "transaction_listings_supported": "1",
      "requires_preload": "0",
      "requires_mfa": "0",
      "updated_at": "2014-11-25 16:53:39",
      "max_days": "120"

    },
    {
      "continues":"..."
    }
  ],
  "user_token": "88ms8g90n19lli6l7"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <institutions>
        <institution>
            <slug>adcu</slug>
            <name>Australian Defence Credit Union</name>
            <credentials>
                <credential>
                    <name>Member Number</name>
                    <fieldID>username</fieldID>
                    <type>TEXT</type>
                    <description></description>
                    <values></values>
                </credential>
                <credential>
                    <name>Access Code</name>
                    <fieldID>password</fieldID>
                    <type>password</type>
                    <description></description>
                    <values></values>
                </credential>
            </credentials>
            <status></status>
            <searchable>1</searchable>
            <display>0</display>
            <searchVal>australiandefencecreditunionadcu</searchVal>
            <region>au</region>
            <export_with_password>0</export_with_password>
            <estatements_supported>1</estatements_supported>
            <transaction_listings_supported>1</transaction_listings_supported>
            <requires_preload>0</requires_preload>
            <requires_mfa>0</requires_mfa>
            <updated_at>2015-05-25 11:58:55</updated_at>
            <max_days>180</max_days>
        </institution>
    <continues>
    </continues>
  </institutions>
</xml>

DESCRIPTION

Get a list of all available institutions.

FUNCTION

Request Part	Value
`Type`	GET
`URL`	/institutions

REQUEST HEADER

Name	Required	Value
`X-API-KEY`		Your API key (see API Keys)
`Content-Type`		The data format of your request (see Request Data Format)
`Accept`		The desired data format of the response (see Response Data Format)

URL Parameters

Name Required Value

region

The region you would like the institution list for. This defaults to whatever is the default for your account, your country of operation. The following values are accepted

Value	Region
`au`	Australia
`nz`	New Zealand
`uk`	United Kingdom
`<empty string>`	Global - all regions

RETURN RESPONSE

An array of all currently supported financial institutions, and all relevant information about them, and the credentials required to log in with that institutions.

POST Request:

{
  "institution": "bankvic"
}

<xml>
  <institution>bankvic</institution>
</xml>

Response:

{
    "institution": {
        "slug": "bankvic",
        "name": "BankVic ",
        "credentials": [
            {
                "name": "Member Number",
                "fieldID": "username",
                "type": "TEXT",
                "description": "",
                "values": ""
            },
            {
                "name": "Password",
                "fieldID": "password",
                "type": "password",
                "description": "",
                "values": ""
            },
            {
                "name": "Enter the text from the image",
                "fieldID": "captcha",
                "type": "captcha",
                "description": "",
                "values": "",
                "src": "data:image/gif;base64,R0l...Ds=",
                "width": 300,
                "height": 60,
                "alt": ""
            }
        ],
        "status": "",
        "searchable": "1",
        "display": "0",
        "searchVal": "bankvicpolicefinancialserviceslimitedvictoria",
        "region": "au",
        "export_with_password": "1",
        "estatements_supported": "0",
        "transaction_listings_supported": "0",
        "requires_preload": "1",
        "requires_mfa": "0",
        "updated_at": "2015-05-25 11:58:56",
        "max_days": "180"
    },
    "user_token": "e29a64c4c9f08414cc2999a0166664f8"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <institution>
        <slug>bankvic</slug>
        <name>BankVic </name>
        <credentials>
            <credential>
                <name>Member Number</name>
                <fieldID>username</fieldID>
                <type>TEXT</type>
                <description></description>
                <values></values>
            </credential>
            <credential>
                <name>Password</name>
                <fieldID>password</fieldID>
                <type>password</type>
                <description></description>
                <values></values>
            </credential>
            <credential>
                <name>Enter the text from the image</name>
                <fieldID>captcha</fieldID>
                <type>captcha</type>
                <description></description>
                <values></values>
                <src>data:image/gif;base64,R0l...AA7</src>
                <width>300</width>
                <height>60</height>
                <alt></alt>
            </credential>
        </credentials>
        <status></status>
        <searchable>1</searchable>
        <display>0</display>
        <searchVal>bankvicpolicefinancialserviceslimitedvictoria</searchVal>
        <region>au</region>
        <export_with_password>1</export_with_password>
        <estatements_supported>0</estatements_supported>
        <transaction_listings_supported>0</transaction_listings_supported>
        <requires_preload>1</requires_preload>
        <requires_mfa>0</requires_mfa>
        <updated_at>2015-05-25 11:58:56</updated_at>
        <max_days>180</max_days>
    </institution>
    <user_token>f5f91637b068c28902aec6669e8902a7</user_token>
</xml>

DESCRIPTION

For some institutions, it is necessary to perform a “preload” step before a Login API function can be attempted. This is generally a requirement for banks that include a Captcha as part of their login process. The preload will load the data necessary for a login to a specified bank. It is possible to determine which banks require this additional step by reviewing the requires_preload attribute for each bank identified via the List Institutions API Function. If the value is 1, then the bank requires this preload step.

FUNCTION

This API function supports both the GET and POST request types to perform the preload action and provide the parameter that indicates which bank must be pre-loaded.

Request Part	Value
`Type`	GET
`URL`	/preload?institution=`bank-slug`

`Type`	POST
`URL`	/preload

REQUEST HEADER

Name	Required	Value
`X-API-KEY`		Your API key (see API Keys)
`Content-Type`		The data format of your request (see Request Data Format)
`Accept`		The desired data format of the response (see Response Data Format)

REQUEST BODY

This is for POST requests only, as the required parameters for GET requests are provided in the URL query string.

Name	Required	Value
`institution`		The slug of the institution of which a subsequent login will be performed.

RETURN RESPONSE

An updated institution object, including the Captcha required to login in, for the requested institution. If the institution does not have a Captcha or otherwise require preload, then this will be exactly the same as the institution object provided by the call to List Institutions. The Captcha image will be base64 encoded, and can be used directly in the src attribute of an img tag. The return value will also include a user_token which must be included in the subsequent call to Login or Login Fetch All Statements.

In most cases, you will not have a user_token to provide to this function, but will just use the one returned from it for the subsequent calls. However, if you are calling this function from the server side after initialising a client-side request, then you will need to provide the user_token to this function, either as a GET/POST parameter or header value

Request:

{
    "credentials": {
        "institution": "cba",
        "username": "12345678",
        "password": "B4nk5ta7m3nt"
    },
    "referral_code": "TEST-123456"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <credentials>
    <institution>cba</institution>
    <username>12345678</username>
    <password>B4nk5ta7m3nt</password>
  </credentials>
  <referral_code>TEST-12345</referral_code>
</xml>

Response:

{
   "accounts":[
      {
         "name":"Everyday Account",
         "accountNumber":"12344321",
         "id":0,
         "bsb":"123-456",
         "balance":"112.31",
         "available":"95.67",
         "accountHolder": "Mr A C Holder",
         "accountHolderType": "single",
         "accountType": "transaction"
      },
      {
         "name":"Savings Account",
         "accountNumber":"98766789",
         "id":1,
         "bsb":"123-456",
         "balance":"115.20",
         "available":"115.20",
         "accountHolder": "Mr A C Holder",
         "accountHolderType": "single",
         "accountType": "savings"
      }
   ],
   "user_token":"a5e0...6156b"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <accounts>
        <account>
            <name>Everyday Account</name>
            <accountNumber>12344321</accountNumber>
            <id>0</id>
            <bsb>123-456</bsb>
            <balance>1.00</balance>
            <available>1.00</available>
            <accountHolder>Mr A C Holder</accountHolder>
            <accountHolderType>single</accountHolderType>
            <accountType>transaction</accountType>
        </account>
        <account>
            <name>Savings Account</name>
            <accountNumber>98766789</accountNumber>
            <id>1</id>
            <bsb>123-456</bsb>
            <balance>2.27</balance>
            <available>2.27</available>
            <accountHolder>Mr A C Holder</accountHolder>
            <accountHolderType>single</accountHolderType>
            <accountType>savings</accountType>
        </account>
    </accounts>
    <user_token>a5e0...6156b</user_token>
</xml>

DESCRIPTION

Log in to a single financial institution, and fetch a list of available accounts at that institution. An optional Referral Code can be provided as part of this request.

FUNCTION

Request Part	Value
`Type`	POST
`URL`	/login

Note that if a Login Preload was made prior to this request, then it is necessary to provide the user_token from the Login Preload response as part of this request, in order to maintain the session information.

REQUEST HEADER

Name	Required	Value
`X-API-KEY`		Your API key (see API Keys)
`Content-Type`		The data format of your request (see Request Data Format)
`Accept`		The desired data format of the response (see Response Data Format)
`X-USER-TOKEN`		This may be a required parameter if a Login Preload was made prior to this request, and the `user_token` is not specified as part of the Request Body. It must be a valid `user_token` for the current session.

REQUEST BODY

Name	Required	Value
`credentials`		This must be present and must contain all the individual `credential` objects that are required for logging into the user’s institution Example Attributes `institution`: The slug of the institution with which the customer’s login credentials will be used. `username`: The username of the customer’s online banking account. `password`: The password of the customer’s online banking account. Typically, the required fields can be identified in the institution’s `credentials` definition and it is the `fieldId` that must be used as part of this login request.

RETURN RESPONSE

Array of accounts found at that institution, with some basic data about the account so that you can determine which of the accounts you would like to Retrieve Statement Data for. A list of possible values for the accountType can be found in Bank Account Types.

List Accounts

Response:

{
   "accounts":[
      {
         "name":"Everyday Account",
         "accountNumber":"12344321",
         "id":0,
         "bsb":"123-456",
         "balance":"112.31",
         "available":"95.67",
         "accountHolder": "Mr A C Holder",
         "accountHolderType": "single",
         "accountType": "transaction"
      },
      {
         "name":"Savings Account",
         "accountNumber":"98766789",
         "id":1,
         "bsb":"123-456",
         "balance":"115.20",
         "available":"115.20",
         "accountHolder": "Mr A C Holder",
         "accountHolderType": "single",
         "accountType": "savings"
      }
   ],
   "user_token":"a5e0...6156b"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <accounts>
        <account>
            <name>Everyday Account</name>
            <accountNumber>12344321</accountNumber>
            <id>0</id>
            <bsb>123-456</bsb>
            <balance>1.00</balance>
            <available>1.00</available>
            <accountHolder>Mr A C Holder</accountHolder>
            <accountHolderType>single</accountHolderType>
            <accountType>transaction</accountType>
        </account>
        <account>
            <name>Savings Account</name>
            <accountNumber>98766789</accountNumber>
            <id>1</id>
            <bsb>123-456</bsb>
            <balance>2.27</balance>
            <available>2.27</available>
            <accountHolder>Mr A C Holder</accountHolder>
            <accountHolderType>single</accountHolderType>
            <accountType>savings</accountType>
        </account>
    </accounts>
    <user_token>a5e0...6156b</user_token>
</xml>

DESCRIPTION

Load a list of accounts available in the current export session.

FUNCTION

Request Part	Value
`Type`	GET
`URL`	/accounts

REQUEST HEADER

Name	Required	Value
`X-API-KEY`		Your API key (see API Keys)
`Accept`		The desired data format of the response (see Response Data Format)
`X-USER-TOKEN`		A `user_token` must be specified with the request, either as this header or as a GET parameter.

RETURN RESPONSE

Array of accounts associated with the current session, with some basic data about each account so that you can determine which of the accounts you would like to Retrieve Statement Data for. A list of possible values for the accountType can be found in Bank Account Types. This response matches the response from Login. It is generally most useful when using the Client Side Functions

Identify

Request for all available data:

{
  "user_token": "e29a64c4c9f08414cc2999a0166664f8",
  "accounts":{
    "bendigo":[0]
  }
}

<xml>
  <user_token>1ebf...8093</user_token>
   <accounts>
    <bendigo>
      <value>0</value>
    </bendigo>
  </accounts>
</xml>

Response:

{
    "bendigo": {
        "referralCode": "my-test",
        "submissionTime": "2020-04-23 12:41:14",
        "bankData": {
            "bankName": "Bendigo Bank",
            "bankSlug": "bendigo"
        },
        "verificationReport": {
            "generalData": {
                "address": {
                    "text": "111 SAMPLE RD ROSTREVOR SA 5073",
                    "streetLine": "111 SAMPLE RD",
                    "streetNumber": "111",
                    "streetName": "SAMPLE",
                    "streetType": "Road",
                    "suburb": "Rostrevor",
                    "stateCode": "SA",
                    "state": "South Australia",
                    "postcode": "5073",
                    "countryCode": "au"
                },
                "accountHolder": "A C HOLDER",
                "phone": "0410499999",
                "email": "test@test.com.au"
            },
            "cards": [],
            "accounts": [
                {
                    "accountHolder": "A C Holder",
                    "bsb": "666000",
                    "accountNumber": "155609999",
                    "accountType": "savings",
                    "accountNickname": "Savings Account 1"
                }
            ]
        }
    },
    "user_token": "khtgfi8233ktf8lrnllp9l6r26",
    "referral_code": "my-test"
}

<xml>
    <bendigo>
        <referralCode>my-test</referralCode>
        <submissionTime>2020-04-23 13:02:30</submissionTime>
        <bankData>
            <bankName>Bendigo Bank</bankName>
            <bankSlug>bendigo</bankSlug>
        </bankData>
        <verificationReport>
            <generalData>
                <address>
                    <text>111 SAMPLE RD ROSTREVOR SA 5073</text>
                    <streetLine>111 SAMPLE RD</streetLine>
                    <levelNumber/>
                    <levelType/>
                    <buildingName/>
                    <unitNumber/>
                    <unitType/>
                    <streetNumber>111</streetNumber>
                    <streetName>SAMPLE</streetName>
                    <streetType>Road</streetType>
                    <streetSuffix/>
                    <suburb>Rostrevor</suburb>
                    <state>South Australia</state>
                    <stateCode>SA</stateCode>
                    <postcode>5073</postcode>
                    <country/>
                    <countryCode>au</countryCode>
                </address>
                <accountHolder>A C HOLDER</accountHolder>
                <phone>0410499999</phone>
                <email>test@test.com.au</email>
            </generalData>
            <cards/>
            <accounts>
                <account>
                    <accountHolder>A C HOLDER</accountHolder>
                    <bsb>666000</bsb>
                    <accountNumber>155609999</accountNumber>
                    <accountType>savings</accountType>
                    <accountNickname>Savings Account 1</accountNickname>
                </account>
            </accounts>
        </verificationReport>
    </bendigo>
    <user_token>khtgfi8233ktf8lrnllp9l6r26</user_token>
    <referral_code>my-test</referral_code>
</xml>

DESCRIPTION

Retrieve account identification data from a customer.

This can only be called oncce a Login request has been successfully submitted, and a valid user token has been received.

FUNCTION

Request Part	Value
`Type`	POST
`URL`	/identify

REQUEST HEADER

Name	Required	Value
`X-API-KEY`		Your API key (see API Keys)
`Content-Type`		The data format of your request (see Request Data Format)
`Accept`		The desired data format of the response (see Response Data Format)
`X-OUTPUT-VERSION`		The desired version of this API function to implement (see API Versions) Supported values: `20170401`
`X-USER-TOKEN`		This may be a required parameter if the `user_token` is not specified as part of the Request Body. It must be a valid `user_token` for the current session.

REQUEST BODY

This function requires the user_token and the account IDs for the accounts that should be included.

The Identify function should only be called once per Login session.

Name	Required	Value
`user_token`		This should be the `user_token` value from the previously received response (i.e. the response from the Login request).
`accounts`		This must contain a child element that is the `bank-slug` of the bank for which the statement data will be retrieved. Its value must be an array of the `ID` for the accounts that you want to retrieve data. The `ID` can be determined from the response received after a successful Login request. You shouldn’t depend on any particular value being displayed as the ID.

RETURN RESPONSE

The response data will contain all the possible identification information from the customer’s accounts.

Retrieve Statement Data

Request for all available data:

{
  "user_token": "e29a64c4c9f08414cc2999a0166664f8",
  "accounts":{
    "boq":[0, 1]
  }
}

<xml>
  <user_token>1ebf...8093</user_token>
   <accounts>
    <boq>
      <value>0</value>
      <value>1</value>
    </boq>
  </accounts>
</xml>

Request with optional parameters for data within a date range:

{
  "user_token": "1ebf...8093",
  "accounts":{
    "boq":[0]
  },
  "requestNumDays":50
}

<xml>
  <user_token>1ebf...8093</user_token>
   <accounts>
    <boq>
      <value>0</value>
    </boq>
  </accounts>
  <requestNumDays>50</requestNumDays>
</xml>

Request (with Password):

{
  "user_token": "1ebf...8093",
  "accounts":{
    "awacu":[0]
  },
  "password": "MySecretPassword"
}

<xml>
  <user_token>1ebf...8093</user_token>
  <accounts>
    <awacu>
      <value>0</value>
    </awacu>
  </accounts>
  <password>MySecretPassword</password>
</xml>

Response:

{
  "accounts": {
    "boq": {
      "accounts": [
        {
          "name": "Day2Day Plus",
          "accountNumber": "22035291",
          "id": 0,
          "bsb": "124-001",
          "balance": "1.00",
          "available": "1.00",
          "accountHolder": "Mr A C Holder",
          "accountHolderType": "single",
          "accountType": "transaction",
          "statementData": {
            "details": [
              {
                "date": "09-06-2015",
                "text": "TFR TO ACCOUNT 022114714 IB2-25238951",
                "notes": null,
                "amount": 1.01,
                "type": "Debit",
                "balance": "1.00"
              },
              {
                "date": "14-12-2014",
                "text": "TFR FROM 022114714 IB2-06194359",
                "notes": null,
                "amount": 1.01,
                "type": "Credit",
                "balance": "2.16"
              }
            ],
            "totalCredits": "8.17",
            "totalDebits": "8.32",
            "openingBalance": "1.15",
            "closingBalance": "1.00",
            "startDate": "12-12-2014",
            "endDate": "17-06-2015",
            "minBalance": "0.00",
            "maxBalance": "2.16",
            "dayEndBalances": [
              {
                "date": "10-06-2015",
                "balance": "1.00"
              }
            ],
            "minDayEndBalance": null,
            "daysInNegative": 0,
            "errorMessage": "",
            "analysis": { }
          },
          "institution": "Bank of Queensland"
        }
      ]
    }
  },
  "user_token": "1ebf...8093"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <accounts>
        <boq>
            <accounts>
                <account>
                    <name>WebSavings</name>
                    <accountNumber>22114714</accountNumber>
                    <id>0</id>
                    <bsb>124-001</bsb>
                    <balance>2.27</balance>
                    <available>2.27</available>
                    <accountHolder>Mr A C Holder</accountHolder>
                    <accountHolderType>single</accountHolderType>
                    <accountType>transaction</accountType>
                    <statementData>
                        <details>
                            <detail>
                                <date>09-06-2015</date>
                                <text>TFR FROM 022035291 IB2-25238951</text>
                                <notes></notes>
                                <amount>1.01</amount>
                                <type>Credit</type>
                                <balance>2.27</balance>
                            </detail>
                            <detail>
                                <date>14-12-2014</date>
                                <text>TFR TO ACCOUNT 022035291 IB2-06194359</text>
                                <notes></notes>
                                <amount>1.01</amount>
                                <type>Debit</type>
                                <balance>1.11</balance>
                            </detail>
                        </details>
                        <totalCredits>8.32</totalCredits>
                        <totalDebits>8.17</totalDebits>
                        <openingBalance>2.12</openingBalance>
                        <closingBalance>2.27</closingBalance>
                        <startDate>12-12-2014</startDate>
                        <endDate>17-06-2015</endDate>
                        <minBalance>1.11</minBalance>
                        <maxBalance>3.27</maxBalance>
                        <dayEndBalances>
                            <dayEndBalance>
                                <date>2016-06-10</date>
                                <balance>123.45</balance>
                            </dayEndBalance>
                        </dayEndBalances>
                        <minDayEndBalance></minDayEndBalance>
                        <daysInNegative>0</daysInNegative>
                        <errorMessage></errorMessage>
                        <analysis/>
                    </statementData>
                    <institution>Bank of Queensland</institution>
                </account>
            </accounts>
        </boq>
    </accounts>
    <user_token>1ebf...8093</user_token>
</xml>

Example Data Response, for version '20160527’:

{
  "reference": "cda8...351f",
  "submissionTime": "2016-06-21T15:33:00",
  "bankData": {
    "bankName": "Bank of Statements",
    "bankSlug": "bank_of_statements",
    "bankAccounts": [
      {
        "id": 0,
        "accountType": "transaction",
        "accountHolder": "Mary Jones",
        "accountHolderType": "single",
        "accountName": "Transaction Account",
        "bsb": "123-456",
        "accountNumber": "456789",
        "currentBalance": "123.45",
        "availableBalance": "123.45",
        "transactions": [
          {
            "date": "2016-06-14",
            "text": "Interest - current rate is 1.05%",
            "amount": 0,
            "type": "Informational",
            "balance": "123.45",
            "tags": [
              {
                "category": "Information"
              }
            ]
          }
        ],
        "statementSummary": {
          "openingBalance": "-125.99",
          "totalCredits": "8184.21",
          "totalDebits": "-7934.77",
          "closingBalance": "123.45",
          "minBalance": "-1279.49",
          "minDayEndBalance": "-1279.49",
          "daysInNegative": 51,
          "searchPeriodStart": "2016-03-23",
          "searchPeriodEnd": "2016-06-17",
          "transactionsStartDate": "2016-03-24",
          "transactionsEndDate": "2016-06-14"
        },
        "dayEndBalances": [
          {
            "date": "2016-06-17",
            "balance": "123.45"
          }
        ],
        "additionalDetails": [],
        "statementAnalysis": [ ]
      }
    ]
  },
  "user_token": "18cf...d839"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <reference>cda8...351f</reference>
    <submissionTime>2016-06-21T15:33:00</submissionTime>
    <bankData>
        <bankName>Bank of Statements</bankName>
        <bankSlug>bank_of_statements</bankSlug>
        <bankAccounts>
            <bankAccount>
                <id>0</id>
                <accountType>transaction</accountType>
                <accountHolder>Mary Jones</accountHolder>
                <accountHolderType>single</accountHolderType>
                <accountName>Transaction Account</accountName>
                <bsb>123-456</bsb>
                <accountNumber>456789</accountNumber>
                <currentBalance>123.45</currentBalance>
                <availableBalance>123.45</availableBalance>
                <transactions>
                    <transaction>
                        <date>2016-06-14</date>
                        <text>Interest - current rate is 1.05%</text>
                        <amount>0</amount>
                        <type>Informational</type>
                        <balance>123.45</balance>
                        <tags>
                            <tag>
                                <category>Information</category>
                            </tag>
                        </tags>
                    </transaction>
                </transactions>
                <statementSummary>
                    <openingBalance>-125.99</openingBalance>
                    <totalCredits>8184.2</totalCredits>
                    <totalDebits>-7934.77</totalDebits>
                    <closingBalance>123.45</closingBalance>
                    <minBalance>-1279.49</minBalance>
                    <minDayEndBalance>-1279.49</minDayEndBalance>
                    <daysInNegative>51</daysInNegative>
                    <searchPeriodStart>2016-03-23</searchPeriodStart>
                    <searchPeriodEnd>2016-06-17</searchPeriodEnd>
                    <transactionsStartDate>2016-03-24</transactionsStartDate>
                    <transactionsEndDate>2016-06-14</transactionsEndDate>
                </statementSummary>
                <dayEndBalances>
                    <dayEndBalance>
                        <date>2016-06-17</date>
                        <balance>123.45</balance>
                    </dayEndBalance>
                </dayEndBalances>
                <additionalDetails></additionalDetails>
                <statementAnalysis></statementAnalysis>
            </bankAccount>
        </bankAccounts>
    </bankData>
    <user_token>18cf...d839</user_token>
</xml>

DESCRIPTION

Retrieve the statement data from a customer’s accounts. It will include all transaction as well as some summary and analysis data.

This can only be called a Login request has been successfully submitted, and a valid user token has been received.

FUNCTION

Request Part	Value
`Type`	POST
`URL`	/statements

REQUEST HEADER

Name	Required	Value
`X-API-KEY`		Your API key (see API Keys)
`Content-Type`		The data format of your request (see Request Data Format)
`Accept`		The desired data format of the response (see Response Data Format)
`X-OUTPUT-VERSION`		The desired version of this API function to implement (see API Versions) Supported values: `20160527` `20170401`
`X-USER-TOKEN`		This may be a required parameter if the `user_token` is not specified as part of the Request Body. It must be a valid `user_token` for the current session.

REQUEST BODY

This function requires the user_token and the account IDs for the accounts that should be included in the export. The transactions from the specified account(s) can be restricted to a date range of a specified number of days prior to the current date, via an option parameter requestNumDays.

The statements function should only be called once per Login session.

Name	Required	Value
`user_token`		This should be the `user_token` value from the previously received response (i.e. the response from the Login request).
`accounts`		This must contain a child element that is the `bank-slug` of the bank for which the statement data will be retrieved. Its value must be an array of the `ID` for the accounts that you want to retrieve data. The `ID` can be determined from the response received after a successful Login request. You shouldn’t depend on any particular value being displayed as the ID.
`requestNumDays`		The number of days prior to the current date for which you want to restrict the data returned. It provides the ability to retrieve transaction data from a specified number of days prior to the current date, up until the current date.
`password`		If an institution has `export_with_password` set, then the user’s password must be included in the request. We recommend not ever storing the user’s password on disk, in a database or in session storage. If the the password cannot be retained in memory until it is needed for this API call, then we recommend asking for the user to submit it again.
`generate_raw_file`		Default is `false`. If set to `true` then BankStatements will produce a file containing the raw bank data. You will then be able to perform a request to Retrieve Files to obtain the actual file. The format of the data in the file will be determined by the account settings of the `X-API-KEY` that is being used. Note: This parameter was previously called `with_raw_file`. These parameters have exactly the same effect, and if either is set to true then it will be considered as set to true. The older with_raw_file parameter name is deprecated, and should not be used in new code.

RETURN RESPONSE

The response data format will depend on the value of the X-OUTPUT-VERSION HTTP header (if it was included), and it will contain all the available account and statement data for the account(s) specified. If requestNumDays was included in the request, then the statement data will be restricted to the relevant time period.

As part of this function, BankStatements, will also potentially generate HTML/PDF statement files of the data retrieved from the user’s bank. The files that might be generated will be determined by the account settings of the X-API-KEY that is being used. If generate_raw_file was set to true as part of the request, then BankStatements will also generate a file containing the response data. Once the response has been received, you will be able to use the user_token provided to perform a Retrieve Files request.

If you have set the X-OUTPUT-VERSION then the statement data output will reflect the version number that you requested. See the API Versions information for more details.

Request

{
  "credentials": {
    "institution": "anz",
    "username": "3584651",
    "password": "secr3tP4s$w0rd"
  },
  "referral_code": "TEST-123456",
  "silent": 0,
  "async": 1,
  "callback": "https://test.example.com/data.php",
  "requestNumDays":50
}

<xml>
  <credentials>
    <institution>anz</institution>
    <username>3584651</username>
    <password>secr3tP4s$w0rd</password>
  </credentials>
  <referral_code>TEST-12345</referral_code>
  <silent>0</silent>
  <async>1</async>
  <callback>https://test.example.com/data.php</callback>
  <requestNumDays>50</requestNumDays>
</xml>

Response

{
  "accounts": {
    "boq": {
      "accounts": [
        {
          "name": "Day2Day Plus",
          "accountNumber": "22035291",
          "id": 0,
          "bsb": "124-001",
          "balance": "1.00",
          "available": "1.00",
          "accountHolder": "Mr A C Holder",
          "accountHolderType": "single",
          "accountType": "transaction",
          "statementData": {
            "details": [
              {
                "date": "09-06-2015",
                "text": "TFR TO ACCOUNT 022114714 IB2-25238951",
                "notes": null,
                "amount": 1.01,
                "type": "Debit",
                "balance": "1.00"
              },
              {
                "date": "14-12-2014",
                "text": "TFR FROM 022114714 IB2-06194359",
                "notes": null,
                "amount": 1.01,
                "type": "Credit",
                "balance": "2.16"
              }
            ],
            "totalCredits": "8.17",
            "totalDebits": "8.32",
            "openingBalance": "1.15",
            "closingBalance": "1.00",
            "startDate": {
              "date": "2014-12-12 13:17:17.000000",
              "timezone_type": 3,
              "timezone": "Australia/Adelaide"
            },
            "endDate": {
              "date": "2015-06-10 13:17:17.000000",
              "timezone_type": 3,
              "timezone": "Australia/Adelaide"
            },
            "minBalance": "0.00",
            "maxBalance": "2.16",
            "dayEndBalances": [],
            "minDayEndBalance": null,
            "daysInNegative": 0,
            "errorMessage": ""
          },
          "institution": "Bank of Queensland"
        }
      ]
    }
  },
  "user_token": "cd7ef53597923fa13dbf4ffeddc97c7f"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <accounts>
        <account>
            <name>WebSavings</name>
            <accountNumber>22114714</accountNumber>
            <id>0</id>
            <bsb>124-001</bsb>
            <balance>2.27</balance>
            <available>2.27</available>
            <accountHolder>Mr A C Holder</accountHolder>
            <accountHolderType>single</accountHolderType>
            <accountType>transaction</accountType>
            <statementData>
                <details>
                    <detail>
                        <date>09-06-2015</date>
                        <text>TFR FROM 022035291 IB2-25238951</text>
                        <notes></notes>
                        <amount>1.01</amount>
                        <type>Credit</type>
                        <balance>2.27</balance>
                    </detail>
                    <detail>
                        <date>14-12-2014</date>
                        <text>TFR TO ACCOUNT 022035291 IB2-06194359</text>
                        <notes></notes>
                        <amount>1.01</amount>
                        <type>Debit</type>
                        <balance>1.11</balance>
                    </detail>
                </details>
                <totalCredits>8.32</totalCredits>
                <totalDebits>8.17</totalDebits>
                <openingBalance>2.12</openingBalance>
                <closingBalance>2.27</closingBalance>
                <startDate>
                    <date>2014-12-12 13:25:10.000000</date>
                    <timezone_type>3</timezone_type>
                    <timezone>Australia/Adelaide</timezone>
                </startDate>
                <endDate>
                    <date>2015-06-10 13:25:10.000000</date>
                    <timezone_type>3</timezone_type>
                    <timezone>Australia/Adelaide</timezone>
                </endDate>
                <minBalance>1.11</minBalance>
                <maxBalance>3.27</maxBalance>
                <dayEndBalances/>
                <minDayEndBalance></minDayEndBalance>
                <daysInNegative>0</daysInNegative>
                <errorMessage></errorMessage>
            </statementData>
            <institution>Bank of Queensland</institution>
        </account>
    </accounts>
    <user_token>1ebf619404f848bedad2d3e6b1288093</user_token>
</xml>

Example Data Response, for version '20160527’:

{
  "reference": "cda8...351f",
  "submissionTime": "2016-06-21T15:33:00",
  "bankData": {
    "bankName": "Bank of Statements",
    "bankSlug": "bank_of_statements",
    "bankAccounts": [
      {
        "id": 0,
        "accountType": "transaction",
        "accountHolder": "Mary Jones",
        "accountHolderType": "single",
        "accountName": "Transaction Account",
        "bsb": "123-456",
        "accountNumber": "456789",
        "currentBalance": "123.45",
        "availableBalance": "123.45",
        "transactions": [
          {
            "date": "2016-06-14",
            "text": "Interest - current rate is 1.05%",
            "amount": 0,
            "type": "Informational",
            "balance": "123.45",
            "tags": [
              {
                "category": "Information"
              }
            ]
          }
        ],
        "statementSummary": {
          "openingBalance": "-125.99",
          "totalCredits": "8184.21",
          "totalDebits": "-7934.77",
          "closingBalance": "123.45",
          "minBalance": "-1279.49",
          "minDayEndBalance": "-1279.49",
          "daysInNegative": 51,
          "searchPeriodStart": "2016-03-23",
          "searchPeriodEnd": "2016-06-17",
          "transactionsStartDate": "2016-03-24",
          "transactionsEndDate": "2016-06-14"
        },
        "dayEndBalances": [
          {
            "date": "2016-06-17",
            "balance": "123.45"
          }
        ],
        "additionalDetails": [],
        "statementAnalysis": [ ]
      }
    ]
  },
  "user_token": "n6oegpo5k28lgoqprigsms9am5"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <reference>cda8...351f</reference>
    <submissionTime>2016-06-21T15:33:00</submissionTime>
    <bankData>
        <bankName>Bank of Statements</bankName>
        <bankSlug>bank_of_statements</bankSlug>
        <bankAccounts>
            <bankAccount>
                <id>0</id>
                <accountType>transaction</accountType>
                <accountHolder>Mary Jones</accountHolder>
                <accountHolderType>single</accountHolderType>
                <accountName>Transaction Account</accountName>
                <bsb>123-456</bsb>
                <accountNumber>456789</accountNumber>
                <currentBalance>123.45</currentBalance>
                <availableBalance>123.45</availableBalance>
                <transactions>
                    <transaction>
                        <date>2016-06-14</date>
                        <text>Interest - current rate is 1.05%</text>
                        <amount>0</amount>
                        <type>Informational</type>
                        <balance>123.45</balance>
                        <tags>
                            <tag>
                                <category>Information</category>
                            </tag>
                        </tags>
                    </transaction>
                </transactions>
                <statementSummary>
                    <openingBalance>-125.99</openingBalance>
                    <totalCredits>8184.2</totalCredits>
                    <totalDebits>-7934.77</totalDebits>
                    <closingBalance>123.45</closingBalance>
                    <minBalance>-1279.49</minBalance>
                    <minDayEndBalance>-1279.49</minDayEndBalance>
                    <daysInNegative>51</daysInNegative>
                    <searchPeriodStart>2016-03-23</searchPeriodStart>
                    <searchPeriodEnd>2016-06-17</searchPeriodEnd>
                    <transactionsStartDate>2016-03-24</transactionsStartDate>
                    <transactionsEndDate>2016-06-14</transactionsEndDate>
                </statementSummary>
                <dayEndBalances>
                    <dayEndBalance>
                        <date>2016-06-17</date>
                        <balance>123.45</balance>
                    </dayEndBalance>
                </dayEndBalances>
                <additionalDetails></additionalDetails>
                <statementAnalysis></statementAnalysis>
            </bankAccount>
        </bankAccounts>
    </bankData>
    <user_token>18cf...d839</user_token>
</xml>

DESCRIPTION

The transactions from the specified account(s) can be restricted to a date range of a specified number of days prior to the current date, via an option parameter requestNumDays.

FUNCTION

Request Part	Value
`Type`	POST
`URL`	/login_fetch_all

REQUEST HEADER

Name	Required	Value
`X-API-KEY`		Your API key (see API Keys)
`Content-Type`		The data format of your request (see Request Data Format)
`Accept`		The desired data format of the response (see Response Data Format)
`X-OUTPUT-VERSION`		The desired version of this API function to implement (see API Versions) Supported values: `20160527` `20170401`
`X-USER-TOKEN`		This may be a required parameter if a Login Preload was made prior to this request, and the `user_token` is not specified as part of the Request Body. It must be a valid `user_token` for the current session.

REQUEST BODY

Name	Required	Value
`credentials`		This must be present and must contain all the individual `credential` objects that are required for logging into the user’s institution Example Attributes `institution`: The slug of the institution with which the customer’s login credentials will be used. `username`: The username of the customer’s online banking account. `password`: The password of the customer’s online banking account. Typically, the required fields can be identified in the institution’s `credentials` definition and it is the `fieldId` that must be used as part of this login request.
`referral_code`		A unique user identifier (see Referral Codes).
`async`		This is a boolean value with a default of `false` (or `0`). The other possible value is `true` (or `1`). This parameter determines the response output and functionality of this API function. If set to `false`, then this API function will return the export of statement/transaction data from all the available bank account(s). If set to `true`, then this API function will return a list of accounts as soon as the login has succeeded (i.e. the same response as provided by the Login function. The API will then perform the remainder of the export in the background, and submit the final data (i.e. the same response as provided by the Retrieve Statement Data function) to the `callback` URL (which must be specified as part of the request, or as a default for the account).
`errorCallback`		This must be a valid URL, such as https://example.com/errorCallback/. We recommend only using a URL that is secured with HTTPS. If `async` is set to `true`, and if there is any error occurred during the bankstatements retrieval process then this URL will be used as the location to which the error response will be returned. If `async` is set to `false`, then this parameter will be ignored.
`callback`		This must be a valid URL, such as https://example.com/callback/. We recommend only using a URL that is secured with HTTPS. If `async` is set to `true`, then this URL will be used as the location to which the exported data will be returned. If `async` is set to `false`, then this parameter will be ignored.
`callbackFormat`		This must be a valid option for a response Content-Type. Valid values are: `json` `xml` If `async` is set to `true`, then this format will be applied to the exported data that will be returned to the `callback` URL. This allows the content sent to the `callback` URL to be different to the content sent as a response to the application that initiated the API function. If `async` is set to `false`, then this parameter will be ignored.
`silent`		This is a boolean value with a default of `false` (or `0`). The other possible value is `true` (or `1`). If set to `true`, then there will only be minimal output (ie, just a `user_token`) returned instead of the export data.
`requestNumDays`		The number of days prior to the current date for which you want to restrict the data returned. It provides the ability to retrieve transaction data from a specified number of days prior to the current date, up until the current date.
`generate_raw_file`		Default is `false`. If set to `true` then BankStatements will produce a file containing the raw bank data. You will then be able to perform a request to Retrieve Files to obtain the actual file. The format of the data in the file will be determined by the account settings of the `X-API-KEY` that is being used. Note: This parameter was previously called `with_raw_file`. These parameters have exactly the same effect, and if either is set to true then it will be considered as set to true. The older with_raw_file parameter name is deprecated, and should not be used in new code.
`include_files`		Default is `false`. If set to `true` then BankStatements will include all the files that were generated from the user’s bank data (including the file produced via the `generate_raw_file` parameter if it was set) in the data sent to the `callback` URL. `async` must be set to `true` for this to be applied. Note: This parameter was previously called `with_pdf`. These parameters have exactly the same effect, and if either is set to true then it will be considered as set to true. The older with_pdf parameter name is deprecated, and should not be used in new code.

RETURN RESPONSE

If async is set to true, then the response and behaviour of this function will be different. In this scenario the API will return a list of accounts available (i.e. the same response as provided by the Login function), and the statement data (depending on the account settings of the X-API-KEY that is being used) and potentially any generated files (i.e. depending on the include_files parameter) will be sent as a POST request to the callback URL.

If you have set the X-OUTPUT-VERSION then the statement data output will reflect the version number that you requested. See the API Versions information for more details.

Retrieve Files

DESCRIPTION

Retrieve any files that were loaded or generated via the BankStatements service as part of previous API requests from the current session. The types of documents that can be provided include BankStatement branded statements, the bank’s own “e-statements”, bank branded transaction listings, and potentially other reports in the future.

It is important to understand that this function does not cause any content to be retrieved from the bank, but instead will only be able to return data that exists in the current temporary session as a result of a successful request to the Retrieve Statement Data or Login Fetch All Statements API functions. This means that if the session expires, or the pre-requisite API functions have not previously been requested successfully for the current session, then no files can be provided.

FUNCTION

Request Part	Value
`Type`	GET
`URL`	/files?user_token=`user_token`

`Type`	GET
`URL`	/files

The user_token must be provided as either a HTTP header parameter or as a GET parameter.

REQUEST HEADER

Name	Required	Value
`X-API-KEY`		Your API key (see API Keys)
`Content-Type`		The data format of your request (see Request Data Format)
`Accept`		The desired data format of the response (see Response Data Format)
`X-USER-TOKEN`		This may be a required parameter if the `user_token` is not specified as part of the URL query string. It must be a valid `user_token` for the current session.

RETURN RESPONSE

If successful, the response will be a ZIP file containing all the available files, and will have a Content-Type HTTP header value of application/x-zip.

If there are no files available or some other error occurred, then an error response will be provided. The Content-Type HTTP header of the response can help you to differentiate what response type (i.e. a ZIP or an error message) the API is returning.

Merge and Deduplicate Raw data

Request:

{
  "file":"File.json",
  "performOutputSubmission": false,
  "async": false
}

API Response example:

{
  "dataVersion": 20190901,
  "reference": "TEST",
  "submissionTime": "2022-11-02T11:03:57",
  "banks": [{
    "bankName": "Bank of Statements",
    "bankSlug": "bank_of_statements",
    "errors": [],
    "bankAccounts": [
      {
        "id": 0,
        "accountType": "transaction",
        "accountHolder": "Mary Jones",
        "accountHolderType": "single",
        "accountName": "Transaction Account",
        "bsb": "123-456",
        "accountNumber": "456789",
        "currentBalance": "123.45",
        "availableBalance": "123.45",
        "transactions": [
          {
            "date": "2022-11-02",
            "description": "Transaction desc",
            "amount": -222.2,
            "balance": "123.45",
            "type": "",
            "tags": [
              {
                "pending": "pending"
              },
              {
                "creditDebit": "debit"
              }
            ],
            "transactionHash": "",
            "logo": "",
            "suburb": ""
          }
        ],
        "statementSummary": {
          "openingBalance": "3994.14",
          "totalCredits": "13826.31",
          "totalDebits": "-17697.00",
          "closingBalance": "123.45",
          "minBalance": "123.45",
          "minDayEndBalance": "123.45",
          "daysInNegative": 0,
          "searchPeriodStart": "2022-05-06",
          "searchPeriodEnd": "2022-11-02",
          "transactionsStartDate": "2022-05-06",
          "transactionsEndDate": "2022-11-02",
          "creditsCategorised": "11582.27",
          "creditsUncategorised": "2244.04",
          "debitsCategorised": "-16414.82",
          "debitsUncategorised": "-1282.18",
          "internalTransferDebits": "0.00",
          "internalTransferCredits": "0.00",
          "accountMovement": "3870.69",
          "dayEndBalances": [],
          "statementAnalysis": [],
          "additionalDetails": {
            "interestRate": "",
            "email": "XXXXXXXX@gmail.com",
            "openDate": "2019-06-27",
            "phone": "XXXX XXX 123",
            "address": {
              "text": "LEVEL 3,Unit 6,11 NORTH TCE,KENT TOWN,SA,5067",
              "streetLine": "LEVEL 3 Unit 6 11 NORTH TCE",
              "levelNumber": "3",
              "levelType": "Level",
              "buildingName": "",
              "unitNumber": "6",
              "unitType": "Unit",
              "streetNumber": "11",
              "streetName": "NORTH",
              "streetType": "Terrace",
              "streetSuffix": "",
              "suburb": "Kent town",
              "state": "South Australia",
              "stateCode": "SA",
              "postcode": "5067",
              "country": "",
              "countryCode": "au"
            }
          }
        }
      }]
    }]
}

DESCRIPTION

Evaluate each file (2019 jsons only) submitted by the API based on time and date of the original submission. And merge it into one raw file with recent transaction date in order (and therefore duplicated data).

FUNCTION

Request Part	Value
`Type`	POST
`URL`	/merge_statements

REQUEST HEADER

Name	Required	Value
`X-API-KEY`		Your API key (see API Keys)
`Content-Type`		multipart/form-data

REQUEST BODY

Name	Required	Value
`file`		Illion 2019 Raw JSON only (see API 20190901 Version)
`referenceCode`		Reference code for the output JSON and html files
`performOutputSubmission`		This is a boolean value with a default of `false`. The other possible value is `true` . Once the parameter is set to true, the api will submitted to client setting’s delivery option.
`async`		This is a boolean value with a default of `false`. The other possible value is `true` . This parameter should be used when `performOutputSubmission` is set to true

RETURN RESPONSE

In response body, the API resopnse will have the merged raw JSON data. As part of this function, BankStatements, will also potentially generate HTML/PDF statement files of the data retrieved from the uploaded files if performOutputSubmission is set to true. The files that might be generated will be determined by the account settings of the X-API-KEY that is being used.

Logout

Request:

{
  "user_token":"e29a64c4c9f08414cc2999a0166664f8"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <user_token>e29a64c4c9f08414cc2999a0166664f8</user_token>
</xml>

DESCRIPTION

Terminate the session referenced by the supplied user_token, and invalidate the token.

As a best practice, this function should be called whenever your application has finished accessing a user’s account, rather than simply leaving the session to expire/timeout. This will ensure that the data stored in the session is removed from memory as early as possible.

FUNCTION

Request Part	Value
`Type`	POST
`URL`	/logout

REQUEST HEADER

The function must include the user_token as a POST parameter (i.e. as part of the query string of the URL), or if it is omitted from the URL, then it must be provided as a HTTP header parameter.

Name	Required	Value
`X-API-KEY`		Your API key (see API Keys)
`Content-Type`		The data format of your request (see Request Data Format)
`Accept`		The desired data format of the response (see Response Data Format)
`X-USER-TOKEN`		This may be a required parameter if the `user_token` is not specified as part of the URL query string.

REQUEST BODY

Name	Required	Value
`user_token`		This should be the `user_token` value from the current session, which you want to terminate. This can be omitted from the Request Body if it is provided as a HTTP header parameter.

RETURN RESPONSE

The response will have a 200 OK response code, but will otherwise not have a “body” or provide other data.

Multi-Factor Authentication

Some banks use a secondary login in addition to the username and password combination, in order to provide a secondary level of security. This is often called 2-factor, or or multi-factor authentication (MFA). This additional authentication may be in the form of an additional password sent to a user token or mobile phone, a set of images from which some need to be selected, or a secret question. Some banks require a user to correctly type the letters from an image, called a CAPTCHA, before being able to log in.

BankStatements deals with these situations by returning a response containing a MFA Request. This request will detail the additional information that is required, which will generally need to be provided by the end user themselves. Only after this MFA step is successfully completed will BankStatements be able to complete the original API request.

MFA Request

When a bank requires additional authentication details in order to finalise a login, the API will return a response containing a MFA Request. This type of request can be identified by the mfa element that is present in the returned response, referred to as the MFA Object, and this will be accompanied by a user_token element.

As each bank/institution require different MFA information, the format of the MFA Object provides the description of the required data in a consistent format.

MFA REQUEST ELEMENTS

API Response with a MFA Request:

{
  "mfa": {
    "title": "Additional authentication step",
    "fields": [{
      "type": "header",
      "value": "SMS security code"
    }, {
      "id": "answer",
      "label": "A SMS security code has been sent to your registered mobile phone. Please enter the code to sign in",
      "type": "input",
      "htmlAttrs": {
        "placeholder": "answer"
      }
    }]
  },
  "user_token": "7b...6f38a"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <mfa>
        <title>Additional authentication step</title>
        <fields>
            <field>
                <type>header</type>
                <value>SMS security code</value>
            </field>
            <field>
                <id>answer</id>
                <label>A SMS security code has been sent to your registered mobile phone. Please enter the code to sign in</label>
                <type>input</type>
                <htmlAttrs>
                    <placeholder>answer</placeholder>
                </htmlAttrs>
            </field>
        </fields>
    </mfa>
    <user_token>7b...6f38a</user_token>
</xml>

Element	Description
`mfa`	This can be used to identify the API response as a MFA Request, and is referred to as a MFA Object.
`user_token`	This is include in the API along with the `mfa` object itself, and should be used in the subsequent MFA Request in order to finalise the authentication process. See User Token.

MFA OBJECT ELEMENTS

Element	Description
`title`	This is a user friendly description of what the MFA is requesting. This can normally be displayed as a heading in the application that is interacting with the API, in order to permit the end user to provide the requested information.
`fields`	A MFA Object will contain one or more objects inside the `fields` array. This is referred to as the MFA Field Object. These fields explain what input the MFA Request requires from the end user in order to proceed, and often will indicate how the fields should be presented to the end user.

The MFA Field Object

Element	Description
`type`	An MFA Field Object will always contain a `type` attribute. The type determines which other attributes will be available, and how that field should be rendered/displayed in the application that is interacting with the API. Refer to the MFA Field Types list to learn more about possible types.
`id`	Any field which requires a value to be returned as part of the MFA Response will have an `id` attribute. This must be used as the key for the data when it is submitted (ie, much like a name attribute would be used in a HTML form).
`htmlAttrs`	An associative array of key-value pairs which could be used as attributes in the relevant html element. These will generally not be required as part of the MFA Response, but may be useful when rendering an MFA form in HTML.
`label`	A text label to describe the field. Should be displayed with the field for user prompting.

MFA Field Types

Type	Description
`instructions`	A text based instruction to display to the user to help them understand what to do, not specifically associated with any field. Generally this should be displayed in the order provided as it may relate to a series of fields below or to the MFA process as a whole. Attributes value: the text to display to the user
`input`	A text input field.
`password`	A password input field (input is masked)
`hidden`	A hidden input. Attributes value: the value which must be submitted back to us. Or sometimes this may be a placeholder for a value which must be calculated
`button`	A button input which will cause some kind of action. Usually linked with some Javascript.
`html`	Some raw html to be included on the page. These elements are not required, but will show useful information to the user. May create elements that interact with Javascript. Attributes value: the html to place on the page.
`header`	A text heading. Normally displayed larger and bolder than regular text, with some margin/padding around it, generally used to define sections or input groups. Attributes value: the text of the heading.
`image`	An image to be displayed. Attributes src: The image source, suitable for placing as the src attribute of an html `<img>` tag. Either as a url, or a base64 encoded image. width: the width of the image in pixels height: the height of the image in pixels
`options`	A set of mutually exclusive options to choose between. May be best rendered as a select box or as a set of radio buttons. Attributes options: An associative array of key-value pairs, where the value is what should be displayed to the user, and the key is what should be submitted if that value is chosen. hint: a suggestion on how this should be rendered. Possible values are radio or select. These do not need to correspond strictly to an html `<select>` tag or list of radio buttons, however the hint will correspond to what the user is more familiar with seeing on their usual bank login screen. A radio suggestion would be best displayed so that the user can see all options, and clicking on one may auto-submit to go on to the next step. A select suggestion may mean the options are more appropriately displayed in a select or combo box.
`set`	A set is a container for a group of fields which are related, and may be more appropriately displayed as a group. The set itself does not necessarily require any specific rendering. Attributes subElements: an array of MFA Fields - these could be a mixture of any of the above types (including possibly further `set` elements, although this is unlikely).
`javascript`	Some javascript code to be included on the page, in an html context. This is usually for convenience of the customer, such as automatically moving the cursor to the next input. For security or other reasons, you may wish to ignore these fields. However, there may be cases where equivalent work functionality will be required, through custom development.

Additional MFA Request Examples

Centrelink example

{
  "mfa": {
    "title": "Secret Question",
    "fields": [{
      "type": "header",
      "value": "Access online services - step 2."
    }, {
      "type": "instructions",
      "value": "Please answer the following secret question."
    }, {
      "id": "answer",
      "label": "What is the name of my dog",
      "type": "input",
      "htmlAttrs": {
        "placeholder": "answer"
      }
    }]
  },
  "user_token": "a0...450aab"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <mfa>
        <title>Secret Question</title>
        <fields>
            <field>
                <type>header</type>
                <value>Access online services - step 2.</value>
            </field>
            <field>
                <type>instructions</type>
                <value>Please answer the following secret question.</value>
            </field>
            <field>
                <id>answer</id>
                <label>What is the name of my dog</label>
                <type>input</type>
                <htmlAttrs>
                    <placeholder>answer</placeholder>
                </htmlAttrs>
            </field>
        </fields>
    </mfa>
    <user_token>a0...450aab</user_token>
</xml>

HSBC (Security Device)

{
  "mfa": {
    "title": "Log in with your Online Security Device",
    "fields": [{
      "type": "header",
      "value": "Enter Password"
    }, {
      "type": "password",
      "id": "memorableAnswer"
    }, {
      "type": "header",
      "value": "Enter Security Code"
    }, {
      "type": "instructions",
      "value": "Please enter your 6 digit Security Code generated by your Online Security Device."
    }, {
      "type": "password",
      "id": "idv_OtpCredential",
      "label": "Security Code (6 digits)"
    }]
  },
  "user_token": "03...38f615a"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <mfa>
        <title>Log in with your Online Security Device</title>
        <fields>
            <field>
                <type>header</type>
                <value>Enter Password</value>
            </field>
            <field>
                <type>password</type>
                <id>memorableAnswer</id>
            </field>
            <field>
                <type>header</type>
                <value>Enter Security Code</value>
            </field>
            <field>
                <type>instructions</type>
                <value>Please enter your 6 digit Security Code generated by your Online Security Device.</value>
            </field>
            <field>
                <type>password</type>
                <id>idv_OtpCredential</id>
                <label>Security Code (6 digits)</label>
            </field>
        </fields>
    </mfa>
    <user_token>03...38f615a</user_token>
</xml>

HSBC (Passwords)

{
  "mfa": {
    "title": "Log in to Internet Banking",
    "fields": [{
      "type": "header",
      "id": "",
      "value": "Enter Password"
    }, {
      "type": "password",
      "id": "memorableAnswer",
      "label": ""
    }, {
      "type": "header",
      "id": "",
      "value": "Enter Secondary Password"
    }, {
      "id": "RCCFields",
      "label": "Enter the First, Third and Seventh characters of your Secondary Password.",
      "type": "set",
      "subElements": [{
        "type": "password",
        "id": "RCCfield1",
        "active": true,
        "optional": false,
        "htmlAttrs": {
          "onkeyup": "tabToNextField(this, 1, 'RCCfield2', event)",
          "size": "1",
          "maxlength": "1",
          "autocomplete": "off"
        }
      }, {
        "type": "password",
        "id": "",
        "active": false,
        "optional": true,
        "htmlAttrs": {
          "disabled": "disabled",
          "class": "optional",
          "size": "1",
          "maxlength": "1",
          "autocomplete": "off"
        }
      }, {
        "type": "password",
        "id": "RCCfield2",
        "active": true,
        "optional": false,
        "htmlAttrs": {
          "onkeyup": "tabToNextField(this, 1, 'RCCfield3', event)",
          "size": "1",
          "maxlength": "1",
          "autocomplete": "off"
        }
      }, {
        "type": "password",
        "id": "",
        "active": false,
        "optional": true,
        "htmlAttrs": {
          "disabled": "disabled",
          "class": "optional",
          "size": "1",
          "maxlength": "1",
          "autocomplete": "off"
        }
      }, {
        "type": "password",
        "id": "",
        "active": false,
        "optional": true,
        "htmlAttrs": {
          "disabled": "disabled",
          "class": "optional",
          "size": "1",
          "maxlength": "1",
          "autocomplete": "off"
        }
      }, {
        "type": "password",
        "id": "",
        "active": false,
        "optional": true,
        "htmlAttrs": {
          "disabled": "disabled",
          "class": "optional",
          "size": "1",
          "maxlength": "1",
          "autocomplete": "off"
        }
      }, {
        "type": "password",
        "id": "RCCfield3",
        "active": true,
        "optional": false,
        "htmlAttrs": {
          "onkeyup": "tabToNextField(this, 1, 'RCCfield3', event)",
          "size": "1",
          "maxlength": "1",
          "autocomplete": "off"
        }
      }, {
        "type": "password",
        "id": "",
        "active": false,
        "optional": true,
        "htmlAttrs": {
          "disabled": "disabled",
          "class": "optional",
          "size": "1",
          "maxlength": "1",
          "autocomplete": "off"
        }
      }]
    }, {
      "type": "javascript",
      "id": "",
      "label": "",
      "script": "function tabToNextField(field, limit, next, evt) { evt = (evt) ? evt : event; var charCode = (evt.charCode) ? evt.charCode : ((evt.keyCode) ? evt.keyCode : ((evt.which) ? evt.which : 0)); if (charCode > 31 && field.value.length == limit) { field.form.elements[next].focus(); } }"
    }]
  },
  "user_token": "6b...29ccdaf0"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <mfa>
        <title>Log in to Internet Banking</title>
        <fields>
            <field>
                <type>header</type>
                <id></id>
                <value>Enter Password</value>
            </field>
            <field>
                <type>password</type>
                <id>memorableAnswer</id>
                <label></label>
            </field>
            <field>
                <type>header</type>
                <id></id>
                <value>Enter Secondary Password</value>
            </field>
            <field>
                <id>RCCFields</id>
                <label>Enter the First, Third and Seventh characters of your Secondary Password.</label>
                <type>set</type>
                <subElements>
                    <subElement>
                        <type>password</type>
                        <id>RCCfield1</id>
                        <active>1</active>
                        <optional>0</optional>
                        <htmlAttrs>
                            <onkeyup>tabToNextField(this, 1, 'RCCfield2', event)</onkeyup>
                            <size>1</size>
                            <maxlength>1</maxlength>
                            <autocomplete>off</autocomplete>
                        </htmlAttrs>
                    </subElement>
                    <subElement>
                        <type>password</type>
                        <id></id>
                        <active>0</active>
                        <optional>1</optional>
                        <htmlAttrs>
                            <disabled>disabled</disabled>
                            <class>optional</class>
                            <size>1</size>
                            <maxlength>1</maxlength>
                            <autocomplete>off</autocomplete>
                        </htmlAttrs>
                    </subElement>
                    <subElement>
                        <type>password</type>
                        <id>RCCField2</id>
                        <active>1</active>
                        <optional>0</optional>
                        <htmlAttrs>
                            <onkeyup>tabToNextField(this, 1, 'RCCfield3', event)</onkeyup>
                            <size>1</size>
                            <maxlength>1</maxlength>
                            <autocomplete>off</autocomplete>
                        </htmlAttrs>
                    </subElement>
                    <subElement>
                        <type>password</type>
                        <id></id>
                        <active>0</active>
                        <optional>1</optional>
                        <htmlAttrs>
                            <disabled>disabled</disabled>
                            <class>optional</class>
                            <size>1</size>
                            <maxlength>1</maxlength>
                            <autocomplete>off</autocomplete>
                        </htmlAttrs>
                    </subElement>
                    <subElement>
                        <type>password</type>
                        <id></id>
                        <active>0</active>
                        <optional>1</optional>
                        <htmlAttrs>
                            <disabled>disabled</disabled>
                            <class>optional</class>
                            <size>1</size>
                            <maxlength>1</maxlength>
                            <autocomplete>off</autocomplete>
                        </htmlAttrs>
                    </subElement>
                    <subElement>
                        <type>password</type>
                        <id>RCCField3</id>
                        <active>1</active>
                        <optional>0</optional>
                        <htmlAttrs>
                            <onkeyup>tabToNextField(this, 1, 'RCCfield3', event)</onkeyup>
                            <size>1</size>
                            <maxlength>1</maxlength>
                            <autocomplete>off</autocomplete>
                        </htmlAttrs>
                    </subElement>
                    <subElement>
                        <type>password</type>
                        <id></id>
                        <active>0</active>
                        <optional>1</optional>
                        <htmlAttrs>
                            <disabled>disabled</disabled>
                            <class>optional</class>
                            <size>1</size>
                            <maxlength>1</maxlength>
                            <autocomplete>off</autocomplete>
                        </htmlAttrs>
                    </subElement>
                </subElements>
            </field>
            <field>
                <type>javascript</type>
                <id></id>
                <label></label>
                <script>function tabToNextField(field, limit, next, evt) { evt = (evt) ? evt : event; var charCode = (evt.charCode) ? evt.charCode : ((evt.keyCode) ? evt.keyCode : ((evt.which) ? evt.which : 0)); if (charCode &gt; 31 &amp;&amp; field.value.length == limit) { field.form.elements[next].focus(); } }</script>
            </field>
        </fields>
    </mfa>
    <user_token>6b...29ccdaf0</user_token>
</xml>

We have included different types of MFA Requests from various institutions as examples of the type and formats that can potentially be sent through from different banks/institutions.

Bank specific examples

Some banks have their own more unique multi factor system, that may require your application to be able to specifically handle these logins in order to give users an experience that is similar to their usual login process. We have included a few examples here for you to review.

Bank

Details

HSBC

Note that the user is able to select which MFA option they wish to login with during the standard login process.

HSBC (passwords):

memorableAnswer (password): Standard password field
RCCField (set/passwords): A set of password fields, only those that are active/not optional will have ID’s.
javascript: Runs to allow auto selection of the current password field (not required)
To submit the memorableAnswer must be in the memorableAnswer field and characters in each of their respective RCCFields with an ID.

HSBC (device):

memorableAnswer (password): Password field
idv_OtpCredential (password): Password field where the user enters the password sent to their HSBC device. The sending of the code is automatically processed with the login step.

Please refer to the MFA Test Account Details to find further information of test accounts that you can use to retrieve additional examples that you can examine.

MFA Response

After receiving a MFA Request from the user’s bank/institution, you will need to then display a form to that user to capture the required input. It is then necessary to submit a MFA Response back to the BankStatements API (which then be forwards the data through to the relevant bank/institution). The user_token value that was provided as part of the MFA Request must be included in the MFA Response in order to maintain the session.

In this section we will explain the end-point URL that the MFA Response should be sent to, and also the format of the data that is to be sent.

Please refer to the Multi-Factor Authentication section of this document for more detailed information on MFA requests in general.

DESCRIPTION

MFA Response Example (CBA Bank)

{
  "netcode": "XXX",
  "user_token": "60...de92b"
}

<xml>
  <netcode>XXX</netcode>
  <user_token>60...de92b</user_token>
</xml>

MFA Response Example (HSBC Bank - with Password)

{
  "memorableAnswer": "XXX",
  "RCCField0": "AAA",
  "RCCField2": "BBB",
  "RCCField5": "CCC",
  "user_token": "60...de92b"
}

<xml>
  <memorableAnswer>XXX</memorableAnswer>
  <RCCField0>AAA</RCCField0>
  <RCCField2>BBB</RCCField2>
  <RCCField5>CCC</RCCField5>
  <user_token>60...de92b</user_token>
</xml>

Submit the additional authentication information that was requested in a received MFA Request.

FUNCTION

Request Part	Value
`Type`	POST
`URL`	/mfa

REQUEST HEADER

Name	Required	Value
`X-API-KEY`		Your API key (see API Keys)
`Content-Type`		The format of your request data (see Input Data)
`Accept`		A HTTP Accept Header of the desired response format. If this is omitted, then the default is JSON data type (see Return Data Format)

REQUEST BODY

Name	Required	Value
`user_token`		This should be the `user_token` value from the previously received response.
bank specific field(s)		This must be present and must contain all the individual field objects that were sent in the MFA Request. This ensures that all the information that was requested in the MFA Request can be returned as part of the MFA Response. Note that the number of `<field>` objects returned by the API is subject to change, and so your application should not hard-code any assumptions about the number of fields being returned based on the current state of the API. Additionally, the fields of type hidden will generally contain the value that must be returned as part of the MFA Response. The API may be updated in the future to not include these as part of future MFA Requests. Example fields can be found in the MFA Test Account Details, but the actual fields required will always be specified in the MFA Request.

RETURN RESPONSE

If the MFA Response is successful, then the originally requested API function will be completed, and the response returned will relate to that function.

If the MFA Response is unsuccessful, then it is likely that the most recently received MFA Request will be re-sent in order to provide another opportunity to submit the required information. If a technical error occurs, then an error response will be returned, along with an error code and description of the error. An error response can be identified by the presence of an error element in the response.

Client-Side API Interaction

It is possible to use the API to generate a single use token, called a guid (i.e. Globally Unique IDentifier) that can permit authorised interaction between a customer’s browser and the BankStatements API. This can permit the customer to send their online banking login credentials directly to the BankStatements API to initiate a retrieval, thereby preventing the need for lender to handle the credentials and forward them to the BankStatements API as is required in the traditional API requests.

The process for initialising and executing a Client-Side retrieval is as follows:

Use the Initialise Client-Side Retrieval Request from your application to generate a guid and user_token.
Provide a web page to your customer that contains the functionality to make requests to the BankStatements API. These requests will use the single use guid and user_token retrieved via step 1.
The customer will then select their bank and enter their online bank login details into a form on your web page, and upon submission, your webpage will POST those details directly to the BankStatements API.
The BankStatements API will validate the guid (and know that it originated from your application), and will check that the request was made from a white listed domain to satisfy CORS restrictions. It will then perform the appropriate API functionality, such as Login Preload, Login, or Login and Fetch All.
The API will respond as required (such as with an Error, a MFA request, or with a successful response including the associated data. This may require further user input depending on the response. Your webpage will therefore need to be able to parse and handle the API response to be able to act accordingly (i.e. to handle failed logins, MFA requests, account selection etc), and perform the follow up actions.
When a successful export has occurred, the API will be able to potentially submit the data directly from the API to your specified callback, or potentially simply return the raw data directly to your web app as part of the success response.

A sample implementation is available, which may assist in your testing and development.

Initialise Client-Side Retrieval Request

POST Request:

{
  "referral_code":"TEST-123456"
}

<xml>
  <referral_code>TEST-123456</referral_code>
</xml>

Response:

{
  "guid": "eyJ0...Uco",
  "user_token": "a5e0...6156b",
  "referral_code": "TEST-123456"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <guid>eyJ0...Uco</guid>
    <user_token>a5e0...6156b</user_token>
    <referral_code>TEST-123456</referral_code>
</xml>

DESCRIPTION

To initiate a Client-Side retrieval process, you will need to submit a traditional BankStatements API request that contains your X-API-Key, and an optional referral_code. This allows the API to authenticate your initiation request, and provide you with a guid and user_token that can subsequently be used in the Client-Side API requests. The guid that is generated is valid for a limited time period, a single bank login/retrieval, and can only be used by white listed domains that you have specified previously (i.e. as part of your BankStatements account configuration).

This results in a limited-use token that the customer can use via your website’s domain to interact and authenticate directly with the BankStatements API, without the need for you to expose your secret X-API-Key client side.

FUNCTION

`Type`	POST
`URL`	/init_cs_request

REQUEST HEADER

Name	Required	Value
`X-API-KEY`		Your API key (see API Keys)
`Content-Type`		The data format of your request (see Request Data Format)
`Accept`		The desired data format of the response (see Response Data Format)

REQUEST BODY

Name	Required	Value
`referral_code`		A unique user identifier (see Referral Codes).

RETURN RESPONSE

The response will contain the guid that is to be used as part of the endpoint URL for subsequent requests, as well as a user_token which must be included in the subsequent Client-Side API calls.

POST Request:

{
  "institution":"cba",
  "user_token": "a5e0...6156b"
}

<xml>
  <institution>cba</institution>
  <user_token>a5e0...6156b</user_token>
</xml>

DESCRIPTION

This API function is essentially the same as the traditional Login Preload API function, except that this function requires a valid guid as part of the endpoint URL, and does not require the X-API-Key as a header parameter.

Note that as this will be a CORS request from the user’s browser to the BankStatements API, an OPTIONS pre-flight request will be sent before the actual POST.

FUNCTION

`Type`	POST
`URL`	/cs_preload/`guid`

REQUEST HEADER

Name	Required	Value
`Content-Type`		The data format of your request (see Request Data Format)
`Accept`		The desired data format of the response (see Response Data Format)
`X-OUTPUT-VERSION`		The desired version of this API function to implement (see API Versions) Supported values: `20160527` `20170401`
`X-USER-TOKEN`		This may be a required parameter if the `user_token` is not specified as part of the Request Body. It must be a valid `user_token` for the current session.

REQUEST BODY

Please refer to the Request Body section of Login Preload for more detailed information. Note that you must include the user_token that was generated as part of the Initialise Client-Side Retrieval Request, as either a body or header parameter.

RETURN RESPONSE

Please refer to the Return Response section of Login Preload.

POST Request:

{
  "institution":"cba",
  "user_token": "a5e0...6156b"
}

<xml>
  <institution>cba</institution>
  <user_token>a5e0...6156b</user_token>
</xml>

DESCRIPTION

This API function is essentially the same as the traditional Login API function, except that this function requires a valid guid as part of the endpoint URL, and does not require the X-API-Key as a header parameter.

Note that as this will be a CORS request from the user’s browser to the BankStatements API, an OPTIONS pre-flight request will be sent before the actual POST.

FUNCTION

`Type`	POST
`URL`	/cs_login/`guid`

REQUEST HEADER

Name	Required	Value
`Content-Type`		The data format of your request (see Request Data Format)
`Accept`		The desired data format of the response (see Response Data Format)
`X-OUTPUT-VERSION`		The desired version of this API function to implement (see API Versions) Supported values: `20160527` `20170401`
`X-USER-TOKEN`		This may be a required parameter if the `user_token` is not specified as part of the Request Body. It must be a valid `user_token` for the current session.

REQUEST BODY

Please refer to the Request Body section of Login for more detailed information. Note that you must include the user_token that was generated as part of the Initialise Client-Side Retrieval Request, as either a body or header parameter.

RETURN RESPONSE

Please refer to the Return Response section of Login.

Client-Side MFA Response

POST Request:

{
  "institution":"cba",
  "user_token": "a5e0...6156b"
}

<xml>
  <institution>cba</institution>
  <user_token>a5e0...6156b</user_token>
</xml>

DESCRIPTION

This API function is essentially the same as the traditional MFA Response API function, except that this function requires a valid guid as part of the endpoint URL, and does not require the X-API-Key as a header parameter.

Note that as this will be a CORS request from the user’s browser to the BankStatements API, an OPTIONS pre-flight request will be sent before the actual POST.

FUNCTION

`Type`	POST
`URL`	/cs_mfa/`guid`

REQUEST HEADER

Name	Required	Value
`Content-Type`		The data format of your request (see Request Data Format)
`Accept`		The desired data format of the response (see Response Data Format)
`X-OUTPUT-VERSION`		The desired version of this API function to implement (see API Versions) Supported values: `20160527` `20170401`
`X-USER-TOKEN`		This may be a required parameter if the `user_token` is not specified as part of the Request Body. It must be a valid `user_token` for the current session.

REQUEST BODY

Please refer to the Request Body section of MFA Response for more detailed information. Note that you must include the user_token that was generated as part of the Initialise Client-Side Retrieval Request, as either a body or header parameter.

RETURN RESPONSE

Please refer to the Return Response section of MFA Response.

Client-Side Retrieve Statement Data

POST Request:

{
  "institution":"cba",
  "user_token": "a5e0...6156b"
}

<xml>
  <institution>cba</institution>
  <user_token>a5e0...6156b</user_token>
</xml>

DESCRIPTION

This API function is essentially the same as the traditional Retrieve Statement Data API function, except that this function requires a valid guid as part of the endpoint URL, and does not require the X-API-Key as a header parameter.

Note that as this will be a CORS request from the user’s browser to the BankStatements API, an OPTIONS pre-flight request will be sent before the actual POST.

FUNCTION

`Type`	POST
`URL`	/cs_export/`guid`

REQUEST HEADER

Name	Required	Value
`Content-Type`		The data format of your request (see Request Data Format)
`Accept`		The desired data format of the response (see Response Data Format)
`X-OUTPUT-VERSION`		The desired version of this API function to implement (see API Versions) Supported values: `20160527` `20170401`
`X-USER-TOKEN`		This may be a required parameter if the `user_token` is not specified as part of the Request Body. It must be a valid `user_token` for the current session.

REQUEST BODY

Please refer to the Request Body section of Retrieve Statement Data for more detailed information. Note that you must include the user_token that was generated as part of the Initialise Client-Side Retrieval Request, as either a body or header parameter.

RETURN RESPONSE

Please refer to the Return Response section of Retrieve Statement Data.

POST Request:

{
  "institution":"cba",
  "user_token": "a5e0...6156b"
}

<xml>
  <institution>cba</institution>
  <user_token>a5e0...6156b</user_token>
</xml>

DESCRIPTION

This API function is essentially the same as the traditional Login and Fetch All Statements API function, except that this function requires a valid guid as part of the endpoint URL, and does not require the X-API-Key as a header parameter.

FUNCTION

`Type`	POST
`URL`	/cs_login_fetch_all/`guid`

REQUEST HEADER

Name	Required	Value
`Content-Type`		The data format of your request (see Request Data Format)
`Accept`		The desired data format of the response (see Response Data Format)
`X-OUTPUT-VERSION`		The desired version of this API function to implement (see API Versions) Supported values: `20160527` `20170401`
`X-USER-TOKEN`		This may be a required parameter if the `user_token` is not specified as part of the Request Body. It must be a valid `user_token` for the current session.

REQUEST BODY

Please refer to the Request Body section of Login and Fetch All Statements for more detailed information. Note that you must include the user_token that was generated as part of the Initialise Client-Side Retrieval Request, as either a body or header parameter.

RETURN RESPONSE

Please refer to the Return Response section of Login and Fetch All Statements.

Centrelink API Commands

BankStatements allows you to connect directly to Centrelink via a set of API commands that relate specifically to Centrelink. This will allow you to build a customised user interface and experience for you customers to interact with BankStatements, in order to retrieve Centrelink data, without having to retrieve any additional bank statement data.

Developers that implement functionality to connect to the Centrelink API commands should be familiar with the generic process of interacting with BankStatements through the regular API commands.

This section contains details of the API functions available, what parameters they expect, and what data they will return.

CHOOSING THE SERVICE TO LOGIN TO

There are currently two methods for connecting to Centrelink:

Via the direct Centrelink login
Via the myGov login

Typically, each of these login providers will implement Multi-factor Authentication (MFA) to provide extra security, and so these MFA requests must be handled by any application interacting with the Centrelink API commands. It is necessary to chose the service provider being used when sending the initial login request.

PROCESS STEPS

The process for retrieving Centrelink data is as follows:

Use the Centrelink Login API function to provide the end user’s username and password (indicating which service provider should be used to authenticate the login details).
Handle the login response which, on success, will be a MFA Request. On failure it could include an error or timeout response.
Submit the MFA Response.
Handle the subsequent response(s), which could be requests for additional MFA tokens. When the authentication process is completed successfully, a reply containing the raw Centrelink/myGov data retrieved will be returned.
(Optional) Make a request for a Centrelink document.

Centrelink API Process

An alternate process for retrieving Centrelink data is as follows:

Use the Centrelink Login Only API function to provide the end user’s username and password (indicating which service provider should be used to authenticate the login details).
Handle the login response which, on success, will be a MFA Request. On failure it could include an error or timeout response.
Submit the MFA Response.
Handle the subsequent response(s), which could be requests for additional MFA tokens. When the authentication process is completed successfully, a reply containing a simple “successful login” message will be returned to confirm that the authentication was successful.
Use the Centrelink Data API function to initiate the retrieval of the data associated with the login account. A reply containing the raw Centrelink/myGov data retrieved will be returned.
(Optional) Make a request for a Centrelink document.

Centrelink API Process

Centrelink Status Request

DESCRIPTION

Check the availability status of the Centrelink service.

FUNCTION

Request Part	Value
`Type`	GET
`URL`	/centrelink_status

REQUEST HEADER

Name	Required	Value
`X-API-KEY`		Your API key (see API Keys)
`Content-Type`		The data format of your request (see Request Data Format)
`Accept`		The desired data format of the response (see Response Data Format)

RETURN RESPONSE

If the Centrelink service is available, then the response will display the available attribute as true (if the response type is JSON, otherwise if XML the response would display it as 1) See the example Response (Centrelink service is available). If the Centrelink service is not available, then the response will display the available attribute as false (if the response type is JSON, otherwise if XML the response would display it as 0) See the example Response (Centrelink service is not available).

The status will contain a short message that describes the current status of Centrelink Service.

The last_submission_time will display the time of the last successful submission of Centrelink document that we have recorded (i.e. to give an estimated indication of the amount of time that Centrelink has been offline).

Response (Centrelink service is available):

{
  "available": true,
  "status": "Normal",
  "last_submission_time": "2016-08-31 12:57:20",
  "user_token": "ea9c7285d4cb55db9694aed3e784b519"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <available>1</available>
    <status>Normal</status>
    <last_submission_time>2016-08-31 12:57:20</last_submission_time>
    <user_token>ea9c7285d4cb55db9694aed3e784b519</user_token>
</xml>

Response (Centrelink service is not available):

{
  "available": false,
  "status": "Centrelink is currently down",
  "last_submission_time": "2016-08-31 12:57:20",
  "user_token": "ea9c7285d4cb55db9694aed3e784b519"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <available>0</available>
    <status>Centrelink is currently down</status>
    <last_submission_time>2016-08-31 12:57:20</last_submission_time>
    <user_token>ea9c7285d4cb55db9694aed3e784b519</user_token>
</xml>

Request (Replace with valid credentials):

{
  "credentials": {
    "username": "XXX",
    "password": "YYY"
  },
  "service": "centrelink",
  "referral_code": "TEST-845821"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <credentials>
    <username>XXX</username>
    <password>YYY</password>
  </credentials>
  <service>centrelink</service>
  <referral_code>TEST-845821</referral_code>
</xml>

DESCRIPTION

Log in to a user’s Centrelink account (via either the Centrelink service or the myGov service), and initiate a session with the API.

FUNCTION

Request Part	Value
`Type`	POST
`URL`	/centrelink_login

REQUEST HEADER

Name	Required	Value
`X-API-KEY`		Your API key (see API Keys)
`Content-Type`		The data format of your request (see Request Data Format)
`Accept`		The desired data format of the response (see Response Data Format)

REQUEST BODY

Name	Required	Value
`credentials`		This must be present and must contain both the username and password for the user’s login service provider (See information below). Attributes `username`: The end user’s username. `password`: The end user’s password.
`service`		This should be `centrelink` or `mygov`. If this is omitted, then the default service is myGov (as Centrelink have advised that soon access will only be available via myGov). An additional value `testcentrelink` can be used to test the Centrelink API and avoid the risk of having incorrectly formatted requests resulting in your Centrelink account potentially being restricted.
`referral_code`		A unique user identifier (see Referral Codes).

The username and password provided must relate to the selected service, and need to be encapsulated within a credentials element. Please refer to the provided examples.

RETURN RESPONSE

Response (MFA example 1 - Centrelink Secret Question):

{
  "mfa": {
    "title": "Secret Question",
    "fields": [{
      "type": "header",
      "value": "Access online services - step 2."
    }, {
      "type": "instructions",
      "value": "Please answer the following secret question."
    }, {
      "id": "answer",
      "label": "What is the name of my dog",
      "type": "input",
      "htmlAttrs": {
        "placeholder": "answer"
      }
    }]
  },
  "user_token": "60...de92b"
}

<xml>
  <mfa>
    <title>Secret Question</title>
    <fields>
      <field>
        <type>header</type>
        <value>Access online services - step 2.</value>
      </field>
      <field>
        <id>answer</id>
        <label>What is the name of my dog</label>
        <type>input</type>
        <htmlAttrs>
          <placeholder>answer</placeholder>
        </htmlAttrs>
      </field>
    </fields>
  </mfa>
  <user_token>60...de92b</user_token>
</xml>

Response (MFA example 2 - myGov Security Code):

{
  "mfa": {
    "title": "myGov security code",
    "fields": [
      {
        "id": "answer",
        "label": "A myGov security code has been sent to your registered mobile phone. \nPlease enter the code to sign in",
        "type": "input",
        "htmlAttrs": {
          "placeholder": "answer"
        }
      }
    ]
  },
  "user_token": "97...0b570"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <mfa>
        <title>myGov security code</title>
        <fields>
            <field>
                <id>answer</id>
                <label>A myGov security code has been sent to your registered mobile phone. Please enter the code to sign in</label>
                <type>input</type>
                <htmlAttrs>
                    <placeholder>answer</placeholder>
                </htmlAttrs>
            </field>
        </fields>
    </mfa>
    <user_token>97...0b570</user_token>
</xml>

Response (MFA example 3 - Centrelink Nominee):

{
  "mfa": {
    "title": "Nominee access to online account - step 3.",
    "fields": [
      {
        "type": "instructions",
        "value": "Your Centrelink account is a nominee and has multiple profiles available. Please select which online account you would like to submit data for."
      },
      {
        "type": "options",
        "id": "content:entryPageForm:entryPageView:chooseAPerson",
        "options": [
          {
            "label": "Myself ",
            "value": "XXX",
            "id": "content:entryPageForm:entryPageView:chooseAPerson:1"
          },
          {
            "label": "Bob Jones ",
            "value": "YYY",
            "id": "content:entryPageForm:entryPageView:chooseAPerson:2"
          }
        ],
        "hint": "radio",
        "label": ""
      },
      {
        "type": "hidden",
        "id": "content:entryPageForm",
        "htmlAttrs": {
          "value": "AAA"
        }
      },
      {
        "type": "hidden",
        "id": "xsrfid",
        "htmlAttrs": {
          "value": "BBB"
        }
      },
      {
        "type": "hidden",
        "id": "pageForm",
        "htmlAttrs": {
          "value": "CCC"
        }
      },
      {
        "type": "hidden",
        "id": "javax.faces.ViewState",
        "htmlAttrs": {
          "value": "DDD"
        }
      },
      {
        "type": "hidden",
        "id": "content:entryPageForm:_idcl",
        "htmlAttrs": {
          "value": "EEE"
        }
      }
    ]
  },
  "user_token": "18...ba010"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <mfa>
        <title>Nominee access to online account - step 3.</title>
        <fields>
            <field>
                <type>instructions</type>
                <value>Your Centrelink account is a nominee and has multiple profiles available. Please select which online account you would like to submit data for.</value>
            </field>
            <field>
                <type>options</type>
                <id>content:entryPageForm:entryPageView:chooseAPerson</id>
                <options>
                    <option>
                        <label>Myself </label>
                        <value>XXX</value>
                        <id>content:entryPageForm:entryPageView:chooseAPerson:1</id>
                    </option>
                    <option>
                        <label>Bob Jones </label>
                        <value>YYY</value>
                        <id>content:entryPageForm:entryPageView:chooseAPerson:2</id>
                    </option>
                </options>
                <hint>radio</hint>
                <label></label>
            </field>
            <field>
                <type>hidden</type>
                <id>content:entryPageForm</id>
                <htmlAttrs>
                    <value>AAA</value>
                </htmlAttrs>
            </field>
            <field>
                <type>hidden</type>
                <id>xsrfid</id>
                <htmlAttrs>
                    <value>BBB</value>
                </htmlAttrs>
            </field>
            <field>
                <type>hidden</type>
                <id>pageForm</id>
                <htmlAttrs>
                    <value>CCC</value>
                </htmlAttrs>
            </field>
            <field>
                <type>hidden</type>
                <id>javax.faces.ViewState</id>
                <htmlAttrs>
                    <value>DDD</value>
                </htmlAttrs>
            </field>
            <field>
                <type>hidden</type>
                <id>content:entryPageForm:_idcl</id>
                <htmlAttrs>
                    <value>EEE</value>
                </htmlAttrs>
            </field>
        </fields>
    </mfa>
    <user_token>18...ba010</user_token>
</xml>

Response (Error example):

{
  "error": "Login Failed",
  "errorCode": 20008,
  "user_token": "41...05c78"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <error>Login Failed</error>
    <errorCode>20008</errorCode>
    <user_token>41...05c78</user_token>
</xml>

Response (Error example with error code):

{
  "error": "The session has expired. Please log in and try the request again.",
  "errorCode": 90002,
  "user_token": "41...05c78"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <error>The session has expired. Please log in and try the request again.</error>
    <errorCode>90002</errorCode>
    <user_token>41...05c78</user_token>
</xml>

If the login is successful, then the response will likely be an MFA Request. It is necessary to submit the requested MFA response in order to finalise the login process. An MFA response can be identified by the presence of an mfa element in the response. See the example Response (MFA example 1) and Response (MFA example 2).

If the login is unsuccessful, then an error response will be returned, along with an error code and description of the error. An error response can be identified by the presence of an error element in the response. See the example Response (Error example).

Regardless of the response type, there will always be a user_token element present that will contain a unique code that must be used in subsequent requests. This will allow session data to be maintained across subsequent requests using the API and MUST be included in subsequent requests. Each new request should use the user_token value from the previous response to ensure that the session is correctly maintained and to avoid session timeouts. See User Token.

Request (Replace with valid credentials):

{
  "credentials": {
    "username": "XXX",
    "password": "YYY"
  },
  "service": "centrelink",
  "referral_code": "TEST-845821"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <credentials>
    <username>XXX</username>
    <password>YYY</password>
  </credentials>
  <service>centrelink</service>
  <referral_code>TEST-845821</referral_code>
</xml>

DESCRIPTION

Log in to a user’s Centrelink account (via either the Centrelink service or the myGov service), and initiate a session with the API. This differs from the Centrelink Login Request in that after completing the Centrelink MFA Response, after a Centrelink Login Only request, the MFA Response will return a simple success message, rather than all the data associated with the account.

This means that an additional request must be made via the Centrelink Data Request API function in order to have the API actually export the customer’s Centrelink data and provide that in a response.

FUNCTION

Request Part	Value
`Type`	POST
`URL`	/centrelink_login_only

REQUEST HEADER

Name	Required	Value
`X-API-KEY`		Your API key (see API Keys)
`Content-Type`		The data format of your request (see Request Data Format)
`Accept`		The desired data format of the response (see Response Data Format)

REQUEST BODY

Name	Required	Value
`credentials`		This must be present and must contain both the username and password for the user’s login service provider (See information below). Attributes `username`: The end user’s username. `password`: The end user’s password.
`service`		This should be `centrelink` or `mygov`. If this is omitted, then the default service is myGov (as Centrelink have advised that soon access will only be available via myGov). An additional value `testcentrelink` can be used to test the Centrelink API and avoid the risk of having incorrectly formatted requests resulting in your Centrelink account potentially being restricted.
`referral_code`		A unique user identifier (see Referral Codes).

The username and password provided must relate to the selected service, and need to be encapsulated within a credentials element. Please refer to the provided examples.

RETURN RESPONSE

Response (MFA example 1 - Centrelink Secret Question):

{
  "mfa": {
    "title": "Secret Question",
    "fields": [{
      "type": "header",
      "value": "Access online services - step 2."
    }, {
      "type": "instructions",
      "value": "Please answer the following secret question."
    }, {
      "id": "answer",
      "label": "What is the name of my dog",
      "type": "input",
      "htmlAttrs": {
        "placeholder": "answer"
      }
    }]
  },
  "user_token": "60...de92b"
}

<xml>
  <mfa>
    <title>Secret Question</title>
    <fields>
      <field>
        <type>header</type>
        <value>Access online services - step 2.</value>
      </field>
      <field>
        <id>answer</id>
        <label>What is the name of my dog</label>
        <type>input</type>
        <htmlAttrs>
          <placeholder>answer</placeholder>
        </htmlAttrs>
      </field>
    </fields>
  </mfa>
  <user_token>60...de92b</user_token>
</xml>

Response (MFA example 2 - myGov Security Code):

{
  "mfa": {
    "title": "myGov security code",
    "fields": [
      {
        "id": "answer",
        "label": "A myGov security code has been sent to your registered mobile phone. \nPlease enter the code to sign in",
        "type": "input",
        "htmlAttrs": {
          "placeholder": "answer"
        }
      }
    ]
  },
  "user_token": "97...0b570"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <mfa>
        <title>myGov security code</title>
        <fields>
            <field>
                <id>answer</id>
                <label>A myGov security code has been sent to your registered mobile phone. Please enter the code to sign in</label>
                <type>input</type>
                <htmlAttrs>
                    <placeholder>answer</placeholder>
                </htmlAttrs>
            </field>
        </fields>
    </mfa>
    <user_token>97...0b570</user_token>
</xml>

Response (MFA example 3 - Centrelink Nominee):

{
  "mfa": {
    "title": "Nominee access to online account - step 3.",
    "fields": [
      {
        "type": "instructions",
        "value": "Your Centrelink account is a nominee and has multiple profiles available. Please select which online account you would like to submit data for."
      },
      {
        "type": "options",
        "id": "content:entryPageForm:entryPageView:chooseAPerson",
        "options": [
          {
            "label": "Myself ",
            "value": "XXX",
            "id": "content:entryPageForm:entryPageView:chooseAPerson:1"
          },
          {
            "label": "Bob Jones ",
            "value": "YYY",
            "id": "content:entryPageForm:entryPageView:chooseAPerson:2"
          }
        ],
        "hint": "radio",
        "label": ""
      },
      {
        "type": "hidden",
        "id": "content:entryPageForm",
        "htmlAttrs": {
          "value": "AAA"
        }
      },
      {
        "type": "hidden",
        "id": "xsrfid",
        "htmlAttrs": {
          "value": "BBB"
        }
      },
      {
        "type": "hidden",
        "id": "pageForm",
        "htmlAttrs": {
          "value": "CCC"
        }
      },
      {
        "type": "hidden",
        "id": "javax.faces.ViewState",
        "htmlAttrs": {
          "value": "DDD"
        }
      },
      {
        "type": "hidden",
        "id": "content:entryPageForm:_idcl",
        "htmlAttrs": {
          "value": "EEE"
        }
      }
    ]
  },
  "user_token": "18...ba010"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <mfa>
        <title>Nominee access to online account - step 3.</title>
        <fields>
            <field>
                <type>instructions</type>
                <value>Your Centrelink account is a nominee and has multiple profiles available. Please select which online account you would like to submit data for.</value>
            </field>
            <field>
                <type>options</type>
                <id>content:entryPageForm:entryPageView:chooseAPerson</id>
                <options>
                    <option>
                        <label>Myself </label>
                        <value>XXX</value>
                        <id>content:entryPageForm:entryPageView:chooseAPerson:1</id>
                    </option>
                    <option>
                        <label>Bob Jones </label>
                        <value>YYY</value>
                        <id>content:entryPageForm:entryPageView:chooseAPerson:2</id>
                    </option>
                </options>
                <hint>radio</hint>
                <label></label>
            </field>
            <field>
                <type>hidden</type>
                <id>content:entryPageForm</id>
                <htmlAttrs>
                    <value>AAA</value>
                </htmlAttrs>
            </field>
            <field>
                <type>hidden</type>
                <id>xsrfid</id>
                <htmlAttrs>
                    <value>BBB</value>
                </htmlAttrs>
            </field>
            <field>
                <type>hidden</type>
                <id>pageForm</id>
                <htmlAttrs>
                    <value>CCC</value>
                </htmlAttrs>
            </field>
            <field>
                <type>hidden</type>
                <id>javax.faces.ViewState</id>
                <htmlAttrs>
                    <value>DDD</value>
                </htmlAttrs>
            </field>
            <field>
                <type>hidden</type>
                <id>content:entryPageForm:_idcl</id>
                <htmlAttrs>
                    <value>EEE</value>
                </htmlAttrs>
            </field>
        </fields>
    </mfa>
    <user_token>18...ba010</user_token>
</xml>

Response (Error example):

{
  "error": "Login Failed",
  "errorCode": 20008,
  "user_token": "41...05c78"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <error>Login Failed</error>
    <errorCode>20008</errorCode>
    <user_token>41...05c78</user_token>
</xml>

Response (Error example with error code):

{
  "error": "The session has expired. Please log in and try the request again.",
  "errorCode": 90002,
  "user_token": "41...05c78"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <error>The session has expired. Please log in and try the request again.</error>
    <errorCode>90002</errorCode>
    <user_token>41...05c78</user_token>
</xml>

Centrelink MFA Response

Request (Example 1 - Centrelink Secret Question response):

{
  "fields": [
    {
      "id": "answer",
      "value": "XXX"
    }
  ],
  "user_token": "60...de92b"
}

<xml>
  <fields>
    <field>
      <id>answer</id>
      <value>XXX</value>
    </field>
  </fields>
  <user_token>60...de92b</user_token>
</xml>

Request (Example 2 - myGov Security Code response):

{
  "fields": [
    {
      "id": "answer",
      "value": "YYY"
    }
  ],
  "user_token": "60...de92b"
}

<xml>
  <fields>
    <field>
      <id>answer</id>
      <value>YYY</value>
    </field>
  </fields>
  <user_token>60...de92b</user_token>
</xml>

Request (Example 3 - Centrelink Nominee response):

{
  "fields": [
    {
      "id": "content:entryPageForm:entryPageView:chooseAPerson",
      "value": "UUU"
    }, {
      "id": "content:entryPageForm",
      "value": "VVV"
    }, {
      "id": "xsrfid",
      "value": "WWW"
    }, {
      "id": "pageForm",
      "value": "XXX"
    }, {
      "id": "javax.faces.ViewState",
      "value": "YYY"
    }, {
      "id": "content:entryPageForm:_idcl",
      "value": "ZZZ"
    }
  ],
  "user_token": "60...de92b"
}

<xml>
  <fields>
    <field>
      <id>content:entryPageForm:entryPageView:chooseAPerson</id>
      <value>UUU</value>
    </field>
    <field>
      <id>content:entryPageForm</id>
      <value>VVV</value>
    </field>
    <field>
      <id>xsrfid</id>
      <value>WWW</value>
    </field>
    <field>
      <id>pageForm</id>
      <value>XXX</value>
    </field>
    <field>
      <id>javax.faces.ViewState</id>
      <value>YYY</value>
    </field>
    <field>
      <id>content:entryPageForm:_idcl</id>
      <value>ZZZ</value>
    </field>
  </fields>
  <user_token>60...de92b</user_token>
</xml>

After successfully submitting a Centrelink Login Only request to the API, it is likely that the selected service provider (i.e. Centrelink or myGov) will respond with a request for a MFA token/answer.

Please refer to the Multi-Factor Authentication section of this document for more detailed information on MFA requests in general, or see Centrelink Login Request for more information about specific Centrelink responses.

DESCRIPTION

Submit a MFA response after receiving an MFA request reply from the API.

FUNCTION

Request Part	Value
`Type`	POST
`URL`	/centrelink_mfa

REQUEST HEADER

Name	Required	Value
`X-API-KEY`		Your API key (see API Keys)
`Content-Type`		The data format of your request (see Request Data Format)
`Accept`		The desired data format of the response (see Response Data Format)

REQUEST BODY

Name	Required	Value
`user_token`		This should be the `user_token` value from the previously received response.
`fields`		This must be present and must contain all the individual field objects that were sent in the MFA Request. This ensures that all the information that was requested in the MFA Request can be returned as part of the MFA Response. Note that the number of `<field>` objects returned by the API is subject to change, and so your application should not hard-code any assumptions about the number of fields being returned based on the current state of the API. Additionally, the fields of type hidden will generally contain the value that must be returned as part of the MFA Response. The API may be updated in the future to not include these as part of future MFA Requests. Attributes `field`: There must always be at least one, but there could be multiple required. `id`: The id of the corresponding MFA Field Object from the MFA Request. `value`: The value to be submitted (which may come from a hidden Field Type in the MFA Request).

RETURN RESPONSE

Response:

{
  "centrelink": {
    "accountHolder": "James John Green",
    "Institution": "Centrelink",
    "CRN": "XXX",
    "referralCode": "TEST-845821",
    "dateOfBirth": {
      "date": "1990-06-30 15:11:02.000000",
      "timezone_type": 3,
      "timezone": "Australia/Adelaide"
    },
    "address": "YYY",
    "postalAddress": "",
    "gender": "Male",
    "data": [
      {
        "date": "29/03/2016",
        "text": "Family Assistance Office",
        "notes": "",
        "type": "Credit",
        "amount": "0.00",
        "netAmount": "0.00",
        "grossAmount": "0.00",
        "breakdown": [
          {
            "description": "Energy Supplement Part A",
            "amount": "0.00",
            "isDeduction": false
          },
          {
            "description": "Energy Supplement Part B",
            "amount": "0.00",
            "isDeduction": false
          },
          {
            "description": "Family Tax Benefit Part A",
            "amount": "0.00",
            "isDeduction": false
          },
          {
            "description": "Family Tax Benefit Part B",
            "amount": "0.00",
            "isDeduction": false
          },
          {
            "description": "Newborn Supplement",
            "amount": "0.00",
            "isDeduction": false
          },
          {
            "description": "Rent Assistance",
            "amount": "0.00",
            "isDeduction": false
          }
        ],
        "tags": []
      },
      {
        "date": "15/03/2016",
        "text": "Family Assistance Office",
        "notes": "",
        "type": "Credit",
        "amount": "0.00",
        "netAmount": "0.00",
        "grossAmount": "0.00",
        "breakdown": [
          {
            "description": "Energy Supplement Part A",
            "amount": "0.00",
            "isDeduction": false
          },
          {
            "description": "Energy Supplement Part B",
            "amount": "0.00",
            "isDeduction": false
          },
          {
            "description": "Family Tax Benefit Part A",
            "amount": "0.00",
            "isDeduction": false
          },
          {
            "description": "Family Tax Benefit Part B",
            "amount": "0.00",
            "isDeduction": false
          },
          {
            "description": "Rent Assistance",
            "amount": "0.00",
            "isDeduction": false
          }
        ],
        "tags": []
      }
    ],
    "analysis": {
      "Income": {
        "Total": {
          "transactionCount": 1,
          "totalValue": 0,
          "monthAvg": 0,
          "avgValue": 0
        },
        "Family Assistance Office": {
          "minValue": "0.00",
          "maxValue": "0.00",
          "transactionCount": 2,
          "totalValue": 0,
          "monthAvg": 0,
          "periodIsRegular": true,
          "firstTransaction": "29/03/2016",
          "period": 14,
          "lastTransaction": "05/01/2016",
          "avgValue": 0,
          "paymentDay": "Tuesday"
        }
      }
    },
    "endDate": "29/03/2016",
    "startDate": "05/01/2016",
    "totalCredits": 0,
    "totalGross": 0,
    "totalDebits": 0,
    "averageCredit": 0
  },
  "available_documents": {
    "generated_data": true,
    "income_statement": true
  },
  "user_token": "32...b962"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <centrelink>
        <accountHolder>James John Green</accountHolder>
        <Institution>Centrelink</Institution>
        <CRN>XXX</CRN>
        <referralCode>TEST-845821</referralCode>
        <dateOfBirth>
            <date>1990-06-30 15:11:02.000000</date>
            <timezone_type>3</timezone_type>
            <timezone>Australia/Adelaide</timezone>
        </dateOfBirth>
        <address>YYY</address>
        <postalAddress></postalAddress>
        <gender>Male</gender>
        <data>
            <datum>
                <date>29/03/2016</date>
                <text>Family Assistance Office</text>
                <notes></notes>
                <type>Credit</type>
                <amount>0.00</amount>
                <netAmount>0.00</netAmount>
                <grossAmount>0.00</grossAmount>
                <breakdown>
                    <item>
                        <description>Energy Supplement Part A</description>
                        <amount>0.00</amount>
                        <isDeduction>0</isDeduction>
                    </item>
                    <item>
                        <description>Energy Supplement Part B</description>
                        <amount>0.00</amount>
                        <isDeduction>0</isDeduction>
                    </item>
                    <item>
                        <description>Family Tax Benefit Part A</description>
                        <amount>0.00</amount>
                        <isDeduction>0</isDeduction>
                    </item>
                    <item>
                        <description>Family Tax Benefit Part B</description>
                        <amount>0.00</amount>
                        <isDeduction>0</isDeduction>
                    </item>
                    <item>
                        <description>Newborn Supplement</description>
                        <amount>0.00</amount>
                        <isDeduction>0</isDeduction>
                    </item>
                    <item>
                        <description>Rent Assistance</description>
                        <amount>0.00</amount>
                        <isDeduction>0</isDeduction>
                    </item>
                </breakdown>
                <tags/>
            </datum>
            <datum>
                <date>15/03/2016</date>
                <text>Family Assistance Office</text>
                <notes></notes>
                <type>Credit</type>
                <amount>0.00</amount>
                <netAmount>0.00</netAmount>
                <grossAmount>0.00</grossAmount>
                <breakdown>
                    <item>
                        <description>Energy Supplement Part A</description>
                        <amount>0.00</amount>
                        <isDeduction>0</isDeduction>
                    </item>
                    <item>
                        <description>Energy Supplement Part B</description>
                        <amount>0.00</amount>
                        <isDeduction>0</isDeduction>
                    </item>
                    <item>
                        <description>Family Tax Benefit Part A</description>
                        <amount>0.00</amount>
                        <isDeduction>0</isDeduction>
                    </item>
                    <item>
                        <description>Family Tax Benefit Part B</description>
                        <amount>0.00</amount>
                        <isDeduction>0</isDeduction>
                    </item>
                    <item>
                        <description>Rent Assistance</description>
                        <amount>0.00</amount>
                        <isDeduction>0</isDeduction>
                    </item>
                </breakdown>
                <tags/>
            </datum>
        </data>
        <analysis>
            <Income>
                <Total>
                    <transactionCount>1</transactionCount>
                    <totalValue>0</totalValue>
                    <monthAvg>0</monthAvg>
                    <avgValue>0</avgValue>
                </Total>
                <FamilyAssistanceOffice>
                    <minValue>0.00</minValue>
                    <maxValue>0.00</maxValue>
                    <transactionCount>2</transactionCount>
                    <totalValue>0</totalValue>
                    <monthAvg>0</monthAvg>
                    <periodIsRegular>1</periodIsRegular>
                    <firstTransaction>29/03/2016</firstTransaction>
                    <period>14</period>
                    <lastTransaction>15/03/2016</lastTransaction>
                    <avgValue>0</avgValue>
                    <paymentDay>Tuesday</paymentDay>
                </FamilyAssistanceOffice>
            </Income>
        </analysis>
        <endDate>29/03/2016</endDate>
        <startDate>15/03/2016</startDate>
        <totalCredits>0</totalCredits>
        <totalGross>0</totalGross>
        <totalDebits>0</totalDebits>
        <averageCredit>0</averageCredit>
    </centrelink>
    <available_documents>
        <generated_data>1</generated_data>
        <income_statement>1</income_statement>
    </available_documents>
    <user_token>32...b962</user_token>
</xml>

Response (Example - no data available):

{
  "error": "Centrelink raw data unavailable.",
  "errorCode": 90001,
  "user_token": "32...b962"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <error>Centrelink raw data unavailable.</error>
  <errorCode>90001</errorCode>
  <user_token>32...b962</user_token>
</xml>

Response if login was performed via “Centrelink Login Only”:

{
  "success": true,
  "message": "Login was successful",
  "user_token": "32...b962"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <success>1</success>
    <message>Login was successful</message>
    <user_token>32...b962</user_token>
</xml>

If the login is successful, then the response could be another MFA Request. In this scenario, the login service provider requires an additional authentication step, and so it is necessary to submit another MFA Response with the additional input data.

If there are no further authentication steps, then the response received will depend on the login function used to initiate the login process, i.e. either Centrelink Login or Centrelink Login Only.

If Centrelink Login, then you should receive a response containing data from the user’s account (i.e. via the centrelink object), and information about any documents that can be potentially retrieved via the Document Request API command (i.e. via the available_documents object). See the example Response.

If Centrelink Login Only, then you should receive a simple success status message to indicate that the login process was successful.

If the MFA Response is unsuccessful, then it is likely that the most recently received MFA Request will be re-sent in order to provide another opportunity to submit the required information. In this scenario, the label part of the response will be slightly different in that it will include a prefixed message indicating that the submitted answer was incorrect, and that the user needs to try again. Note that repeatedly failing this step can cause myGov/Centrelink to temporarily lock the account.

If a technical error occurs, then an error response will be returned, along with an error code and description of the error. An error response can be identified by the presence of an error element in the response.

Centrelink Data Request

Request:

{
  "user_token": "60...de92b"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <user_token>60...de92b</user_token>
</xml>

After successfully performing a Centrelink Login Only Request, including submitting the subsequent MFA responses to the API in order to finalise the authentication process, you will be able to then request that the API provide you with the available data for the customer’s Centrelink account.

DESCRIPTION

Request the customer’s data after a successful Centrelink Login Only Request.

FUNCTION

Request Part	Value
`Type`	POST
`URL`	/centrelink_data

REQUEST HEADER

Name	Required	Value
`X-API-KEY`		Your API key (see API Keys)
`Content-Type`		The data format of your request (see Request Data Format)
`Accept`		The desired data format of the response (see Response Data Format)

REQUEST BODY

Name	Required	Value
`user_token`		This should be the `user_token` value from the previously received response

RETURN RESPONSE

Response:

{
  "centrelink": {
    "accountHolder": "James John Green",
    "Institution": "Centrelink",
    "CRN": "XXX",
    "referralCode": "TEST-845821",
    "dateOfBirth": {
      "date": "1990-06-30 15:11:02.000000",
      "timezone_type": 3,
      "timezone": "Australia/Adelaide"
    },
    "address": "YYY",
    "postalAddress": "",
    "gender": "Male",
    "data": [
      {
        "date": "29/03/2016",
        "text": "Family Assistance Office",
        "notes": "",
        "type": "Credit",
        "amount": "0.00",
        "netAmount": "0.00",
        "grossAmount": "0.00",
        "breakdown": [
          {
            "description": "Energy Supplement Part A",
            "amount": "0.00",
            "isDeduction": false
          },
          {
            "description": "Energy Supplement Part B",
            "amount": "0.00",
            "isDeduction": false
          },
          {
            "description": "Family Tax Benefit Part A",
            "amount": "0.00",
            "isDeduction": false
          },
          {
            "description": "Family Tax Benefit Part B",
            "amount": "0.00",
            "isDeduction": false
          },
          {
            "description": "Newborn Supplement",
            "amount": "0.00",
            "isDeduction": false
          },
          {
            "description": "Rent Assistance",
            "amount": "0.00",
            "isDeduction": false
          }
        ],
        "tags": []
      },
      {
        "date": "15/03/2016",
        "text": "Family Assistance Office",
        "notes": "",
        "type": "Credit",
        "amount": "0.00",
        "netAmount": "0.00",
        "grossAmount": "0.00",
        "breakdown": [
          {
            "description": "Energy Supplement Part A",
            "amount": "0.00",
            "isDeduction": false
          },
          {
            "description": "Energy Supplement Part B",
            "amount": "0.00",
            "isDeduction": false
          },
          {
            "description": "Family Tax Benefit Part A",
            "amount": "0.00",
            "isDeduction": false
          },
          {
            "description": "Family Tax Benefit Part B",
            "amount": "0.00",
            "isDeduction": false
          },
          {
            "description": "Rent Assistance",
            "amount": "0.00",
            "isDeduction": false
          }
        ],
        "tags": []
      }
    ],
    "analysis": {
      "Income": {
        "Total": {
          "transactionCount": 1,
          "totalValue": 0,
          "monthAvg": 0,
          "avgValue": 0
        },
        "Family Assistance Office": {
          "minValue": "0.00",
          "maxValue": "0.00",
          "transactionCount": 2,
          "totalValue": 0,
          "monthAvg": 0,
          "periodIsRegular": true,
          "firstTransaction": "29/03/2016",
          "period": 14,
          "lastTransaction": "05/01/2016",
          "avgValue": 0,
          "paymentDay": "Tuesday"
        }
      }
    },
    "endDate": "29/03/2016",
    "startDate": "05/01/2016",
    "totalCredits": 0,
    "totalGross": 0,
    "totalDebits": 0,
    "averageCredit": 0
  },
  "available_documents": {
    "generated_data": true,
    "income_statement": true
  },
  "user_token": "32...b962"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <centrelink>
        <accountHolder>James John Green</accountHolder>
        <Institution>Centrelink</Institution>
        <CRN>XXX</CRN>
        <referralCode>TEST-845821</referralCode>
        <dateOfBirth>
            <date>1990-06-30 15:11:02.000000</date>
            <timezone_type>3</timezone_type>
            <timezone>Australia/Adelaide</timezone>
        </dateOfBirth>
        <address>YYY</address>
        <postalAddress></postalAddress>
        <gender>Male</gender>
        <data>
            <datum>
                <date>29/03/2016</date>
                <text>Family Assistance Office</text>
                <notes></notes>
                <type>Credit</type>
                <amount>0.00</amount>
                <netAmount>0.00</netAmount>
                <grossAmount>0.00</grossAmount>
                <breakdown>
                    <item>
                        <description>Energy Supplement Part A</description>
                        <amount>0.00</amount>
                        <isDeduction>0</isDeduction>
                    </item>
                    <item>
                        <description>Energy Supplement Part B</description>
                        <amount>0.00</amount>
                        <isDeduction>0</isDeduction>
                    </item>
                    <item>
                        <description>Family Tax Benefit Part A</description>
                        <amount>0.00</amount>
                        <isDeduction>0</isDeduction>
                    </item>
                    <item>
                        <description>Family Tax Benefit Part B</description>
                        <amount>0.00</amount>
                        <isDeduction>0</isDeduction>
                    </item>
                    <item>
                        <description>Newborn Supplement</description>
                        <amount>0.00</amount>
                        <isDeduction>0</isDeduction>
                    </item>
                    <item>
                        <description>Rent Assistance</description>
                        <amount>0.00</amount>
                        <isDeduction>0</isDeduction>
                    </item>
                </breakdown>
                <tags/>
            </datum>
            <datum>
                <date>15/03/2016</date>
                <text>Family Assistance Office</text>
                <notes></notes>
                <type>Credit</type>
                <amount>0.00</amount>
                <netAmount>0.00</netAmount>
                <grossAmount>0.00</grossAmount>
                <breakdown>
                    <item>
                        <description>Energy Supplement Part A</description>
                        <amount>0.00</amount>
                        <isDeduction>0</isDeduction>
                    </item>
                    <item>
                        <description>Energy Supplement Part B</description>
                        <amount>0.00</amount>
                        <isDeduction>0</isDeduction>
                    </item>
                    <item>
                        <description>Family Tax Benefit Part A</description>
                        <amount>0.00</amount>
                        <isDeduction>0</isDeduction>
                    </item>
                    <item>
                        <description>Family Tax Benefit Part B</description>
                        <amount>0.00</amount>
                        <isDeduction>0</isDeduction>
                    </item>
                    <item>
                        <description>Rent Assistance</description>
                        <amount>0.00</amount>
                        <isDeduction>0</isDeduction>
                    </item>
                </breakdown>
                <tags/>
            </datum>
        </data>
        <analysis>
            <Income>
                <Total>
                    <transactionCount>1</transactionCount>
                    <totalValue>0</totalValue>
                    <monthAvg>0</monthAvg>
                    <avgValue>0</avgValue>
                </Total>
                <FamilyAssistanceOffice>
                    <minValue>0.00</minValue>
                    <maxValue>0.00</maxValue>
                    <transactionCount>2</transactionCount>
                    <totalValue>0</totalValue>
                    <monthAvg>0</monthAvg>
                    <periodIsRegular>1</periodIsRegular>
                    <firstTransaction>29/03/2016</firstTransaction>
                    <period>14</period>
                    <lastTransaction>15/03/2016</lastTransaction>
                    <avgValue>0</avgValue>
                    <paymentDay>Tuesday</paymentDay>
                </FamilyAssistanceOffice>
            </Income>
        </analysis>
        <endDate>29/03/2016</endDate>
        <startDate>15/03/2016</startDate>
        <totalCredits>0</totalCredits>
        <totalGross>0</totalGross>
        <totalDebits>0</totalDebits>
        <averageCredit>0</averageCredit>
    </centrelink>
    <available_documents>
        <generated_data>1</generated_data>
        <income_statement>1</income_statement>
    </available_documents>
    <user_token>32...b962</user_token>
</xml>

Response (Example - no data available):

{
  "error": "Centrelink raw data unavailable.",
  "errorCode": 90001,
  "user_token": "32...b962"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <error>Centrelink raw data unavailable.</error>
  <errorCode>90001</errorCode>
  <user_token>32...b962</user_token>
</xml>

If the data retrieval process was successful, then you should receive a response containing data from the user’s account (i.e. via the centrelink object), and information about any documents that can be potentially retrieved via the Document Request API command (i.e. via the available_documents object). See the example Response.

Regardless of the response type, there will always be a user_token element present that will contain a unique code that must be used in subsequent requests. This will allow session data to be maintained across subsequent requests using the API and MUST be included in subsequent requests. Each new request should use the user_token value from the previous response to ensure that the session is correctly maintained (and to avoid session timeouts). See User Token.

Centrelink Document Request

Request (Example 1 - Retrieve the Generated Data):

{
  "document": "generated_data",
  "user_token": "60...de92b"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <document>generated_data</document>
  <user_token>60...de92b</user_token>
</xml>

Request (Example 2 - Retrieve the Income Statement):

{
  "document": "income_statement",
  "user_token": "60...de92b"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <document>income_statement</document>
  <user_token>60...de92b</user_token>
</xml>

After successfully submitting one or more MFA responses to the API, and finalising the authentication process, the API will return a message containing some of the data that was retrieved from Centrelink. Additional document data can be requested via a subsequent API command, requesting the specific document(s) that are required.

DESCRIPTION

Request a document after receiving a successful data reply from the API.

FUNCTION

Request Part	Value
`Type`	POST
`URL`	/centrelink_documents

REQUEST HEADER

Name	Required	Value
`X-API-KEY`		Your API key (see API Keys)
`Content-Type`		The data format of your request (see Request Data Format)
`Accept`		The desired data format of the response (see Response Data Format)

REQUEST BODY

Name	Required	Value
`user_token`		This should be the `user_token` value from the previously received response
`document`		The document type that you want to retrieve. Available document types: `generated_data`: The document that is automatically created by BankStatements of the raw data that was retrieved. (BankStatements branded) `income_statement`: The Centrelink Income Statement (Centrelink branded)

RETURN RESPONSE

Response:

{
  "document_title": "XXXX--incomestatement-mygov---YYYYYYYYYY-e.pdf",
  "document_data": "JVBERi0xLjcNC ... base64 encoded file data ... cNCiUlRU9GDQo=",
  "user_token": "60...de92b"
}

<xml>
  <document_title>XXXX--incomestatement-mygov---YYYYYYYYYY-e.pdf</document_title>
  <document_data>JVBERi0xLjcNC ... base64 encoded file data ... cNCiUlRU9GDQo=</document_data>
  <user_token>60...de92b</user_token>
</xml>

If the login is successful, then the response will contain a document_title field that contain a unique filename for the document that contains the four letter client Referral Code, and also a document_data field that will contain the base64 encoded data for the file.

Centrelink Logout Request

Request:

{
  "user_token":"e29a64c4c9f08414cc2999a0166664f8"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <user_token>e29a64c4c9f08414cc2999a0166664f8</user_token>
</xml>

DESCRIPTION

Terminate the session referenced by the supplied user_token, and invalidate the token. It will ensure that the connection to the service provider is also terminated.

FUNCTION

Request Part	Value
`Type`	POST
`URL`	/centrelink_logout

REQUEST HEADER

The function must include the user_token as a POST parameter (i.e. as part of the query string of the URL), or if it is omitted from the URL, then it must be provided as a HTTP header parameter.

Name	Required	Value
`X-API-KEY`		Your API key (see API Keys)
`Content-Type`		The data format of your request (see Request Data Format)
`Accept`		The desired data format of the response (see Response Data Format)
`X-USER-TOKEN`		This may be a required parameter if the `user_token` is not specified as part of the URL query string.

REQUEST BODY

Name	Required	Value
`user_token`		This should be the `user_token` value from the current session, which you want to terminate. This can be omitted from the Request Body if it is provided as a HTTP header parameter.

RETURN RESPONSE

The response will have a 200 OK response code, but will otherwise not have a “body” or provide other data.

Testing the Centrelink API

In order to allow developers to integrate their software with our Centrelink API and to be able to test the API, we have provided a “test” Centrelink service that will mock the request/response process to retrieve data. This allows developers to make repeated login and MFA responses in order to integrate with the API, without the risk of having any actual Centrelink accounts being restricted due to failed login attempts. It also allows developers to test the document request command to base64 decode on an example known PDF file.

The format for requests and the subsequent responses are the same as the previously documented examples, however it is necessary to perform the Centrelink Login Request using the service testcentrelink.

It is important that you use the URL endpoint https://test.bankstatements.com.au/ rather than https://www.bankstatements.com.au/ in order to use the testcentrelink service provider.

The login request will then be followed by an MFA Request, per the previously documented examples. The login credentials that you use when logging in via the testcentrelink service will determine which MFA Request will be sent via the API. This will allow you to test a variety of different scenarios. The testcentrelink will return the same MFA Requests for each login credential as listed in the following table, however when testing against real myGov and Centrelink accounts you will receive varied requests which will need to be handled correctly.

Username	Password	Notes
`555555555Z`	`ExampleMyGovAccount`	This will simulate a myGov login request, which will require a SMS token (the required value is part of the MFA Request).
`666666666Y`	`ExampleCentrelinkAccount`	This will simulate a Centrelink login request, which will require an answer to a secret question (the required value is part of the MFA Request).
`777777777X`	`ExampleCentrelinkNomineeAccount`	This will simulate a Centrelink login request, which will require an answer to a secret question (the required value is part of the MFA Request). This will then be followed by a nominee access request.
`888888888W`	`ExampleLockedAccount`	This will simulate the scenario where an account has been locked and will return an error message (with an error code) as the response.
`999999999V`	`ExampleNoPaymentHistoryAccount`	This will simulate the scenario where an account has successfully logged in an retrieved the income statement but no payment history was found. In this scenario the response will lack detail for the data and analysis, and the generated statement file will lack the payment history.
`444444444U`	`ExampleNoIncomeStatement`	This will simulate the scenario where an account has successfully logged in, but no income statement can be retrieved. Payment History will be available, but no official centrelink Income Statement will be provided.
`111111111M`	`ExampleNoAccountData`	This will simulate the scenario where an account has successfully logged in an retrieved the income statement but no account data was found. In this scenario the response will lack detail for the data.

After completing the login and MFA Response process, you will then be able to request Centrelink Documents. The example document provided is a simple PDF that says “Hello World”.

Once you have completed your application such that it can submit correctly formatted requests via the testcentrelink service provider, and handle the responses, the next step is to perform real requests via either the centrelink or mygov service providers to ensure that your application can retrieve real data.

Appendix

Additional technical information relating to the BankStatements API can be found within this section:

API Errors
Bank Account Types
Account Holder Types

API Errors

Example error response:

{
  "error": "The login credentials were not supplied, or the request was badly formatted.",
  "errorCode": 19005,
  "user_token": "a8sj...4dc7"
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <error>The login credentials were not supplied, or the request was badly formatted.</error>
    <errorCode>19005</errorCode>
    <user_token>a8sj...4dc7</user_token>
</xml>

When an error occurs and the API returns an error message, the response will consist of an errorCode and a related error message, and potentially a user_token (i.e. only if a user session actually exists). The error code definitions are listed in the following table. For some errors, such as 19001, “A required parameter was missing from the request.”, the error response message may contain additional information specific to that error (i.e. to help identify the parameter that was missing).

Error Code	Meaning
10005	Session expired.
19000	A valid service provider is required.
19001	A required parameter was missing from the request.
19002	The session has expired. Please log in and try the request again.
19003	A required parameter had an invalid value.
19004	The requested document is not available.
19005	The login credentials were not supplied.
19006	An invalid request was made.
19007	The selected service is offline.
19008	There was an error accessing the financial institution. Please try again shortly.
19009	The API reached an invalid state.
19010	The user’s myGov account is not linked to their Centrelink account. The user will need to connect Centrelink to myGov before trying again.
19011	Access to centrelink was denied when trying to transfer from myGov to Centrelink.
20001	There have been too many unsuccessful login attempts.
20002	A required credential was not provided. Please enter all required credentials.
20004	You are currently logged in to your online banking, or have recently logged out. You will need to wait at least 15 minutes before trying again.
20005	Your online banking account has been locked. You will need to check with your bank for resetting your access.’;
20007	Your online banking password has expired. You will need to check with your bank for instructions on resetting your password.
20008	The login process failed.
30001	There was a problem when attempting to log in to your account.
30002	There was a problem when trying to log in to your account.
30003	There was a problem in trying to export statement data for your account.
30004	Your financial institution requires you to perform some manual action before we can export data from your account. Please log in to your financial institution’s online banking (desktop site) and complete the action requested after you log in.
30005	There was an error in reading information from your financial institution.
30006	There was an error in loading your financial institution. Please try again shortly.
30009	There was a problem when trying to log in to your account.
30010	Your bank’s online banking system is currently inaccessible as it is being updated. Please try again in a few hours.
30011	Your bank’s online banking system is currently unavailable. Please try again in a few hours.
32003	The password does not match the one previously entered.
32008	Your online banking setup is not yet finalised. You will need to check with your bank for instructions on completing setup.
40001	There was an error while generating your statements.
40003	Transaction data could not be parsed because the format was not as expected.
40004	Data for the requested period could not be loaded because the institution does not support history going that far back.
40005	Exporting transaction history is temporarily unavailable at this institution.
40010	There was an error while reading data from the institution.
50001	There was a network connection issue while connecting to the bank/institution. The institution’s website could be down or unavailable, or taking too long to respond.
50002	The institution responded with too many redirects.
50005	The credentials do not match the format required by this institution.
50009	An error occurred with the session management system.
50010	An error occurred in connecting to the institution’s website. We are not able to confirm the authenticity of the website’s security certificate.
60001	An unexpected condition was reached. Please try again later.
60006	We were logged out of the institution’s portal before the export could be completed. This can occur if the user logs in to the institution’s website directly while we are performing the export.
60008	There are no accounts available for which we can export data.
60012	The user logged into the bank that does not have full permission to view balances and export transactions.
80001	A change in the institution’s online portal has meant that we cannot currently export data.
80002	A change in the institution’s online portal has meant that we cannot currently export data.
80003	A change in the institution’s online portal has meant that we cannot currently export data.
80004	A change in the institution’s online portal has meant that we cannot currently export data.
80008	A change in the institution’s online portal has meant that we cannot currently export data.
80009	Could not process MFA, question not found.
90001	There was an unknown error.
90002	There was an unknown error.
90003	Multi-factor Authentication is not available for this institution at this time.
110000	There was an error in loading your financial institution. Please try again shortly.
110001	There was an error in loading your financial institution. Please try again shortly.
110002	There was an error in loading your financial institution. Please try again shortly.
110003	There was an error in loading your financial institution. Please try again shortly.
110004	There was an error in loading your financial institution. Please try again shortly.
110009	There was an error in loading your financial institution. Please try again shortly.

Bank Account Types

When the API returns a response containing information about a cusomter’s bank account(s), the response may contain an accountType field that identifies the account type of each bank account. Following is a list of the valid values that may be used to categorise a bank account:

transaction
savings
credit card
personal loan
home loan
car loan
insurance
superannuation
investments
reward card
trading
frequent flyer
shopping reward

Note that it is possible that an empty/blank value is returned if BankStatements cannot determine the account type for some reason.

Account Holder Types

When the API returns a response containing information about a cusomter’s bank account(s), the response may contain an accountHolderType field that identifies the type of the account holder for each account based on the name of the account holder. Following is a list of the valid values that may be used to categorise the account holder:

single
joint
unknown

Note that the accountHolderType field is only returned if there is an accountHolder field explicitly present in the response as well.

Introduction

Getting Started

Referring to our Site or using the iFrame

The Referral Code

The Referring URL

The iFrame URL

Unique Identifiers

Additional Parameters

Javascript Loader

Submission of Data

Returning Control

The API

Getting Started with the API

API URL

API Versions

API Keys

API Data Formats

Request Data Format

Response Data Format

User Token

Customer Referral/Reference Code

Testing

Basic Test Account Details

MFA Test Account Details

Optional MFA Test Account Details

Captcha Test Account Details

Mortgage Test Account Details

Testing Error Conditions

API Functions

Verify API Status

List Institutions

Login Preload

Login

List Accounts

Identify

Retrieve Statement Data

Login and Fetch All Statements

Retrieve Files

Merge and Deduplicate Raw data

Logout

Multi-Factor Authentication

MFA Request

MFA REQUEST ELEMENTS

MFA OBJECT ELEMENTS

The MFA Field Object

MFA Field Types

Additional MFA Request Examples

MFA Response

Client-Side API Interaction

Initialise Client-Side Retrieval Request

Client-Side Login Preload

Client-Side Login

Client-Side MFA Response

Client-Side Retrieve Statement Data

Client-Side Login and Fetch All Statements

Centrelink API Commands

Centrelink Status Request

Centrelink Login Request

Centrelink Login Only Request

Centrelink MFA Response

Centrelink Data Request

Centrelink Document Request

Centrelink Logout Request

Testing the Centrelink API

Appendix

API Errors

Bank Account Types

Account Holder Types