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 |
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 | |
* 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 | |
*[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. 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 | |
* 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.
A push notification has been sent to your registered device for verification.
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 |
---|---|
MFAnetcode | 123456 |
Profile selectionprofile | 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
|
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.
Login Preload
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.
Login
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 |
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 institutionExample Attributes
For HSBC , use following fields:
|
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:
| |
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>
Superannuation, Trading or Loyalty Institution Type Data Response, for version ‘20160527’:
{
"dataVersion": 20160527,
"reference": "XYZY",
"submissionTime": "2024-05-09T09:12:55",
"institutionData": {
"institutionName": "REST Super",
"institutionSlug": "restsuper",
"institutionType": "super",
"institutionAccounts": [
{
"id": 0,
"accountType": "superannuation",
"accountHolder": "Mr John Doe",
"accountName": "REST Super",
"accountNumber": "123456789",
"currentBalance": "12345.25",
"transactions": [
{
"date": "2024-04-30",
"text": "Contributions Tax",
"amount": -123.84,
"transactionHash": "3e3bdfb8d5aa0c881162b84e32faaea1837202xx"
}
]
}
]
},
"user_token": "1t4c0qd3do26jgtuhhi51be7qq",
"referral_code": "AGAT"
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<reference>TEST</reference>
<submissionTime>2024-05-22T17:29:28</submissionTime>
<institutionData>
<institutionName>REST Super</institutionName>
<institutionSlug>restsuper</institutionSlug>
<institutionType>super</institutionType>
<institutionAccounts>
<institutionAccount>
<id>0</id>
<accountType>superannuation</accountType>
<accountHolder>Mr Test Test</accountHolder>
<accountName>REST Super</accountName>
<accountNumber>123456789</accountNumber>
<currentBalance>12345.18</currentBalance>
<transactions>
<transaction>
<date>2024-05-08</date>
<text>Contribution</text>
<amount>123.24</amount>
<transactionHash>d7ca423f4633857a202c92ea7d2d2389265b4c33</transactionHash>
</transaction>
</transactions>
</institutionAccount>
</institutionAccounts>
</institutionData>
<user_token>8vj8pp90mbnhmarsv1dgnpl6xu</user_token>
<referral_code>TEST</referral_code>
</xml>
Superannuation, Trading or Loyalty Institution Type Data Response, for version ‘20170401’:
{
"dataVersion": 20170401,
"reference": "test",
"submissionTime": "2024-05-23T10:22:41",
"institutionData": {
"institutionName": "REST Super",
"institutionSlug": "restsuper",
"institutionType": "super",
"institutionAccounts": [
{
"id": 0,
"accountType": "superannuation",
"accountHolder": "Mr John Doe",
"accountName": "REST Super",
"accountNumber": "123456789",
"currentBalance": "12345.25",
"transactions": [
{
"date": "2024-04-30",
"text": "Contributions Tax",
"amount": -123.84,
"transactionHash": "3e3bdfb8d5aa0c881162b84e32faaea1837202xx"
}
]
}
]
},
"user_token": "eoff6c1sl9rfdldt6ms3eg0jnm",
"referral_code": "test"
}
<?xml version="1.0" encoding="utf-8"?>
<xml dataVersion="20170401">
<reference>TEST</reference>
<submissionTime>2024-05-22T17:33:16</submissionTime>
<institutionData>
<institutionName>REST Super</institutionName>
<institutionSlug>restsuper</institutionSlug>
<institutionType>super</institutionType>
<institutionAccounts>
<institutionAccount>
<id>0</id>
<accountType>superannuation</accountType>
<accountHolder>Mr Test Test</accountHolder>
<accountName>REST Super</accountName>
<accountNumber>123456789</accountNumber>
<currentBalance>12345.18</currentBalance>
<transactions/>
</institutionAccount>
</institutionAccounts>
</institutionData>
<user_token>8vj8pp90mbnhmarsv1dgnpl6xy</user_token>
<referral_code>TEST</referral_code>
</xml>
Superannuation, Trading or Loyalty Institution Type Data Response, for version ‘20190901’:
{
"dataVersion": 20190901,
"reference": "XYZY",
"submissionTime": "2024-05-09T09:13:54",
"institutionData": {
"institutionName": "REST Super",
"institutionSlug": "restsuper",
"institutionType": "super",
"institutionAccounts": [
{
"id": 0,
"accountType": "superannuation",
"accountHolder": "Mr John Doe",
"accountName": "REST Super",
"accountNumber": "123456789",
"currentBalance": "12345.25",
"transactions": []
}
]
},
"user_token": "1t4c0qd3do26jgtuhhi51be7yy",
"referral_code": "AGAT"
}
<?xml version="1.0" encoding="utf-8"?>
<xml dataVersion="20190901">
<reference>TEST</reference>
<submissionTime>2024-05-22T17:37:53</submissionTime>
<institutionData>
<institutionName>REST Super</institutionName>
<institutionSlug>restsuper</institutionSlug>
<institutionType>super</institutionType>
<institutionAccounts>
<institutionAccount>
<id>0</id>
<accountType>superannuation</accountType>
<accountHolder>Mr Test Test</accountHolder>
<accountName>REST Super</accountName>
<accountNumber>123456789</accountNumber>
<currentBalance>12345.18</currentBalance>
<transactions/>
</institutionAccount>
</institutionAccounts>
</institutionData>
<user_token>8vj8pp90mbnhmarsv1dgnpl6xy</user_token>
<referral_code>TEST</referral_code>
</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:
| |
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.
If the institution type is superannuation, trading or loyalty then institutionData property will be returned in the response else bankData property is present. See Example Data Response.
Login and Fetch All Statements
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"
}
Example Data Response, for version ‘20190901’:
{
"dataVersion": 20190901,
"reference": "test",
"submissionTime": "2024-07-23T05:20:08",
"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": "2024-07-23",
"description": "Transaction Details Available Next Business Day",
"amount": -500.44,
"balance": "123.45",
"type": "",
"tags": [
{
"creditDebit": "debit"
}
],
"logo": "",
"suburb": ""
},
{
"date": "2024-07-23",
"description": "Interest - current rate is 1.05%",
"amount": 0,
"balance": "623.89",
"type": "Informational",
"tags": [
{
"category": "Information"
},
{
"creditDebit": "credit"
}
],
"logo": "",
"suburb": ""
},],
"statementSummary": {
"openingBalance": "-975.65",
"totalCredits": "9013.14",
"totalDebits": "-7914.04",
"closingBalance": "123.45",
"minBalance": "-975.65",
"minDayEndBalance": "-819.26",
"daysInNegative": 23,
"searchPeriodStart": "2024-04-24",
"searchPeriodEnd": "2024-07-23",
"transactionsStartDate": "2024-04-26",
"transactionsEndDate": "2024-07-23",
"creditsCategorised": "7556.04",
"creditsUncategorised": "1457.10",
"debitsCategorised": "-7132.07",
"debitsUncategorised": "-781.97",
"internalTransferDebits": "0.00",
"internalTransferCredits": "0.00",
"accountMovement": "-1099.10",
"dayEndBalances": [{
"date": "2024-07-23",
"balance": "123.45"
},
{
"date": "2024-07-22",
"balance": "623.89"
}]
},
"statementAnalysis": [{
"analysisCategory": {
"name": "Wages",
"analysisPoints": [
{
"name": "startDate",
"value": "2024-06-23",
"title": "Start Date",
"type": "date"
},
{
"name": "endDate",
"value": "2024-06-23",
"title": "End Date",
"type": "date"
},
{
"name": "totalAmount",
"value": 480.06,
"title": "Total Amount",
"type": "money"
},
{
"name": "countOfTransactions",
"value": 1,
"title": "Count of Transactions",
"type": "integer"
},
{
"name": "totalAmountLast30Days",
"value": 0,
"title": "Total Amount - Last 30 Days",
"type": "money"
},
{
"name": "monthlyAmountAverage",
"value": "480.06",
"title": "Monthly Average Amount",
"type": "money"
},
{
"name": "averageTransactionAmount",
"value": 480.06,
"title": "Average Transaction Amount",
"type": "money"
},
{
"name": "daysSinceLastTransaction",
"value": 30,
"title": "Days Since Last Transaction",
"type": "integer"
},
{
"name": "totalAmountCredits",
"value": 480.06,
"title": "Total Amount - Credits",
"type": "money"
},
{
"name": "totalAmountDebits",
"value": 0,
"title": "Total Amount - Debits",
"type": "money"
},
{
"name": "countOfProviders",
"value": 1,
"title": "Count of Providers",
"type": "integer"
}
],
"transactionGroups": [
{
"name": "Wage from delivery service job",
"analysisPoints": [
{
"name": "startDate",
"value": "2024-06-23",
"title": "Start Date",
"type": "date"
},
{
"name": "endDate",
"value": "2024-06-23",
"title": "End Date",
"type": "date"
},
{
"name": "totalAmount",
"value": 480.06,
"title": "Total Amount",
"type": "money"
},
{
"name": "frequency",
"value": 0,
"title": "Frequency",
"type": "integer"
},
{
"name": "frequencyDay",
"value": "Sun",
"title": "Frequency Day",
"type": "string"
},
{
"name": "countOfTransactions",
"value": 1,
"title": "Count of Transactions",
"type": "integer"
},
{
"name": "totalAmountLast30Days",
"value": 0,
"title": "Total Amount - Last 30 Days",
"type": "money"
},
{
"name": "monthlyAmountAverage",
"value": "480.06",
"title": "Monthly Average Amount",
"type": "money"
},
{
"name": "averageTransactionAmount",
"value": 480.06,
"title": "Average Transaction Amount",
"type": "money"
},
{
"name": "daysSinceLastTransaction",
"value": 30,
"title": "Days Since Last Transaction",
"type": "integer"
},
{
"name": "totalAmountCredits",
"value": 480.06,
"title": "Total Amount - Credits",
"type": "money"
},
{
"name": "totalAmountDebits",
"value": 0,
"title": "Total Amount - Debits",
"type": "money"
}
],
"transactions": [
{
"date": "2024-06-23",
"description": "Wage from delivery service job",
"amount": 480.06,
"balance": "50.58",
"type": "",
"tags": [
{
"thirdParty": "Wages"
},
{
"category": "Wages"
},
{
"creditDebit": "credit"
}
],
"logo": "",
"suburb": ""
}
]
}
]
}
},],
"additionalDetails": {
"interestRate": "",
"email": "XXXXXXXX@gmail.com",
"openDate": "2021-03-18",
"phone": "XXXX XXX 123",
"periodOfExtractedTransactions": "26-04-2024 to 23-07-2024 (89 days)",
"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"
}
}
},
],
"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"
}
}
],
"decisionMetrics": [
{
"id": "DM085",
"name": "Buy Now Pay Later Monthly",
"descriptor": "",
"type": "money",
"value": "0.00"
}
],
"documentId": "QHR8SFRQ8",
"scoreModels": [
]
}
<?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
Log in to an institution and immediately retrieve/fetch statement data for all accounts found at that institution.
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:
| |
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 institutionExample Attributes
For HSBC , use following fields:
| |
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:
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
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 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
|
input |
A text input field. |
password |
A password input field (input is masked) |
hidden |
A hidden input. Attributes
|
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
|
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
|
image |
An image to be displayed. Attributes
|
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
|
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
|
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 > 31 && 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):
|
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
anduser_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
anduser_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.
Client-Side 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 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:
| |
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.
Client-Side Login
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:
| |
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:
| |
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:
| |
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.
Client-Side Login and Fetch All Statements
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:
| |
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.
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 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>
Centrelink Login Request
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
| |
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). |
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.
Centrelink Login Only Request
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
| |
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). |
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.
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
|
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.
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 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:
|
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.
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.
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 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.
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 | /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
.
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
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.