NAV
Json XML

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

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

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

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

iFrame

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

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

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.

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.

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

Eg - turn it off

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

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

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

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

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:

  1. Determine the base API URL for your API requests.
  2. Obtain an API Key specific to the API environment you will be using.
  3. Determine the data format that you will use to send API requests, and the data format you will use when receiving API responses.
  4. 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:

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 StringDescriptionDetails
<blank>The original version.Details
20160527Simplifies and standardises the raw data format. A complete re-write from the original version.Details
20170401A minor update from the previous version. Makes Analysis Points more consistent, and allows for Decision Metrics which provide key metrics across all accounts.Details
20190901This 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 NameValue
institutionbank_of_statements
username12345678
passwordTestMyMoney

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 NameValue
institutionbank_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

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 NameValue
usernamecba
passwordcba
with-mfawith

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

MFA ResponseTest Value
netcode123456

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 NameValue
usernamewestpac
passwordwestpac
with-mfawith

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

MFA ResponseTest Value
profile1234
profile5678
Credential NameValue
usernamehsbc-device
passwordhsbc-device
with-mfawith

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

MFA ResponseTest Value
memorableAnswer12345678
idv_OtpCredential987654

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 NameValue
usernamehsbc-passwords
passwordhsbc-passwords
with-mfawith

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

MFA ResponseTest Value
memorableAnswer12345678
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.

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 NameValue
usernamerabo
passwordrabo
with-mfawith

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

MFA ResponseTest Value
password98765
The value to submit will come from digipass device.

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 NameValue
usernamerabo
with-mfawith

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

MFA ResponseTest Value
password98765
The value to submit will come from digipass device.

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 NameValue
usernamebendigo
passwordbendigo
with-mfawith

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

MFA ResponseTest Value
is_pushyes
* 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.
generatePushAgainyes
*[OPTIONAL] In case of time out of initial request, generatePushAgain can be sent with value yes to request the push notification again.

Example Response for Bendigo Push Notification:

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

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

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

Example Request for Macquarie Push Notification:

{
    "credentials": {
        "institution": "bank_of_mfa",
        "username": "macquarie",
        "password": "macquarie",
        "with-mfa": "with"
    }
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
  <credentials>
    <institution>bank_of_mfa</institution>
    <username>macquarie</username>
    <password>macquarie</password>
    <with-mfa>with</with-mfa>
  </credentials>
</xml>
Credential NameValue
usernamemacquarie
passwordmacquarie
with-mfawith

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

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

Example Response for Macquarie Push Notification:

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

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 NameValue
usernamemfaExampleHtmlHidden
passwordmfaExampleHtmlHidden
with-mfawith

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

MFA ResponseTest Value
sequence78
* 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.

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 NameValue
usernamemfaExampleButton
passwordmfaExampleButton
with-mfawith

The MFA Response will require the following action.

MFA ResponseTest 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.

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 NameValue
usernamemfaExampleImage
passwordmfaExampleImage
with-mfawith

The MFA Response will require the following action.

MFA ResponseTest 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.

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 NameValue
usernamemfaExampleOptions
passwordmfaExampleOptions
with-mfawith

The MFA Response will require the following action.

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

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 NameValue
usernamemfaAndProfile
passwordmfaAndProfile
with-mfawith

The MFA Response will require the following action.

MFA ResponseTest Value
MFAnetcode123456
Profile selectionprofile1234

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 NameBank Slug
Bank of Optional MFAbank_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 NameValue
usernamewith
passwordwith
date (MFA field)Today's date in Ymd format. Eg 20170718
Credential NameValue
usernamewithout
passwordwithout
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 NameValue
institutionbank_of_captcha
username12345678
passwordTestMyMoney
captchaD49ZHN

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 NameValue
institutionbank_of_mortgage
username12345678
passwordTestMyMoney
institutionbank_of_mortgage
username7777
passwordweekly
institutionbank_of_mortgage
username1414
passwordfortnightly
institutionbank_of_mortgage
username3031
passwordmonthly

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 NameValue
institutionbank_of_statements
usernameerror
passworderror

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

Credential NameValue
institutionbank_of_statements
usernameerror
password30004

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 PartValue
TypeGET
URL/verify

REQUEST HEADER

NameRequiredValue
X-API-KEYYour API key (see API Keys)
Content-TypeThe data format of your request (see Request Data Format)
AcceptThe 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 PartValue
TypeGET
URL/institutions

REQUEST HEADER

NameRequiredValue
X-API-KEYYour API key (see API Keys)
Content-TypeThe data format of your request (see Request Data Format)
AcceptThe desired data format of the response (see Response Data Format)

URL Parameters

NameRequiredValue
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
ValueRegion
auAustralia
nzNew Zealand
ukUnited Kingdom
<empty string>Global - all regions

RETURN RESPONSE

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

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 PartValue
TypeGET
URL/preload?institution=bank-slug
TypePOST
URL/preload

REQUEST HEADER

NameRequiredValue
X-API-KEYYour API key (see API Keys)
Content-TypeThe data format of your request (see Request Data Format)
AcceptThe 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.

NameRequiredValue
institutionThe 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 PartValue
TypePOST
URL/login

REQUEST HEADER

NameRequiredValue
X-API-KEYYour API key (see API Keys)
Content-TypeThe data format of your request (see Request Data Format)
AcceptThe desired data format of the response (see Response Data Format)
X-USER-TOKENThis 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

NameRequiredValue
credentialsThis must be present and must contain all the individual credential objects that are required for logging into the user’s institution

Example Attributes
  • institution: The slug of the institution with which the customer’s login credentials will be used.
  • username: The username of the customer’s online banking account.
  • password: The password of the customer’s online banking account.

    Typically, the required fields can be identified in the institution’s credentials definition and it is the fieldId that must be used as part of this login request.
Note:
For HSBC, use following fields:
  • institution: hsbc
  • username: The username of the customer’s online banking account.
  • login-method: This should be either device or passwords.

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 PartValue
TypeGET
URL/accounts

REQUEST HEADER

NameRequiredValue
X-API-KEYYour API key (see API Keys)
AcceptThe desired data format of the response (see Response Data Format)
X-USER-TOKENA 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 PartValue
TypePOST
URL/identify

REQUEST HEADER

NameRequiredValue
X-API-KEYYour API key (see API Keys)
Content-TypeThe data format of your request (see Request Data Format)
AcceptThe desired data format of the response (see Response Data Format)
X-OUTPUT-VERSIONThe desired version of this API function to implement (see API Versions)

Supported values:
  • 20170401
X-USER-TOKENThis 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.

NameRequiredValue
user_tokenThis should be the user_token value from the previously received response (i.e. the response from the Login request).
accountsThis 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 PartValue
TypePOST
URL/statements

REQUEST HEADER

NameRequiredValue
X-API-KEYYour API key (see API Keys)
Content-TypeThe data format of your request (see Request Data Format)
AcceptThe desired data format of the response (see Response Data Format)
X-OUTPUT-VERSIONThe desired version of this API function to implement (see API Versions)

Supported values:
  • 20160527
  • 20170401
X-USER-TOKENThis 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.

NameRequiredValue
user_tokenThis should be the user_token value from the previously received response (i.e. the response from the Login request).
accountsThis 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.
requestNumDaysThe 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.
passwordIf 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_fileDefault 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 PartValue
TypePOST
URL/login_fetch_all

REQUEST HEADER

NameRequiredValue
X-API-KEYYour API key (see API Keys)
Content-TypeThe data format of your request (see Request Data Format)
AcceptThe desired data format of the response (see Response Data Format)
X-OUTPUT-VERSIONThe desired version of this API function to implement (see API Versions)

Supported values:
  • 20160527
  • 20170401
X-USER-TOKENThis 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

NameRequiredValue
credentialsThis must be present and must contain all the individual credential objects that are required for logging into the user’s institution

Example Attributes
  • institution: The slug of the institution with which the customer’s login credentials will be used.
  • username: The username of the customer’s online banking account.
  • password: The password of the customer’s online banking account.

    Typically, the required fields can be identified in the institution’s credentials definition and it is the fieldId that must be used as part of this login request.
Note:
For HSBC, use following fields:
  • institution: hsbc
  • username: The username of the customer’s online banking account.
  • login-method: This should be either device or passwords.
referral_codeA unique user identifier (see Referral Codes).
asyncThis 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).
errorCallbackThis 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.
callbackThis 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.
callbackFormatThis must be a valid option for a response Content-Type. Valid values are:
  • json
  • xml
If async is set to true, then this format will be applied to the exported data that will be returned to the callback URL. This allows the content sent to the callback URL to be different to the content sent as a response to the application that initiated the API function. If async is set to false, then this parameter will be ignored.
silentThis 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.
requestNumDaysThe 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_fileDefault 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_filesDefault 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 PartValue
TypeGET
URL/files?user_token=user_token
TypeGET
URL/files

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

REQUEST HEADER

NameRequiredValue
X-API-KEYYour API key (see API Keys)
Content-TypeThe data format of your request (see Request Data Format)
AcceptThe desired data format of the response (see Response Data Format)
X-USER-TOKENThis 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 PartValue
TypePOST
URL/merge_statements

REQUEST HEADER

NameRequiredValue
X-API-KEYYour API key (see API Keys)
Content-Typemultipart/form-data

REQUEST BODY

NameRequiredValue
fileIllion 2019 Raw JSON only (see API 20190901 Version)
referenceCodeReference code for the output JSON and html files
performOutputSubmissionThis 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.
asyncThis 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 PartValue
TypePOST
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.

NameRequiredValue
X-API-KEYYour API key (see API Keys)
Content-TypeThe data format of your request (see Request Data Format)
AcceptThe desired data format of the response (see Response Data Format)
X-USER-TOKENThis may be a required parameter if the user_token is not specified as part of the URL query string.

REQUEST BODY

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

RETURN RESPONSE

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

Multi-Factor Authentication

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

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

MFA Request

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

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

MFA REQUEST ELEMENTS

API Response with a MFA Request:

{
  "mfa": {
    "title": "Additional authentication step",
    "fields": [{
      "type": "header",
      "value": "SMS security code"
    }, {
      "id": "answer",
      "label": "A SMS security code has been sent to your registered mobile phone. Please enter the code to sign in",
      "type": "input",
      "htmlAttrs": {
        "placeholder": "answer"
      }
    }]
  },
  "user_token": "7b...6f38a"
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
    <mfa>
        <title>Additional authentication step</title>
        <fields>
            <field>
                <type>header</type>
                <value>SMS security code</value>
            </field>
            <field>
                <id>answer</id>
                <label>A SMS security code has been sent to your registered mobile phone. Please enter the code to sign in</label>
                <type>input</type>
                <htmlAttrs>
                    <placeholder>answer</placeholder>
                </htmlAttrs>
            </field>
        </fields>
    </mfa>
    <user_token>7b...6f38a</user_token>
</xml>
Element Description
mfa This can be used to identify the API response as a MFA Request, and is referred to as a MFA Object.
user_token This is include in the API along with the mfa object itself, and should be used in the subsequent MFA Request in order to finalise the authentication process. See User Token.

MFA OBJECT ELEMENTS

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

The MFA Field Object

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

MFA Field Types

Type Description
instructions A text based instruction to display to the user to help them understand what to do, not specifically associated with any field. Generally this should be displayed in the order provided as it may relate to a series of fields below or to the MFA process as a whole.

Attributes
  • value: the text to display to the user
input A text input field.
password A password input field (input is masked)
hidden A hidden input.

Attributes
  • value: the value which must be submitted back to us. Or sometimes this may be a placeholder for a value which must be calculated
button A button input which will cause some kind of action. Usually linked with some Javascript.
html Some raw html to be included on the page. These elements are not required, but will show useful information to the user. May create elements that interact with Javascript.

Attributes
  • value: the html to place on the page.
header A text heading. Normally displayed larger and bolder than regular text, with some margin/padding around it, generally used to define sections or input groups.

Attributes
  • value: the text of the heading.
image An image to be displayed.

Attributes
  • src: The image source, suitable for placing as the src attribute of an html <img> tag. Either as a url, or a base64 encoded image.
  • width: the width of the image in pixels
  • height: the height of the image in pixels
options A set of mutually exclusive options to choose between. May be best rendered as a select box or as a set of radio buttons.

Attributes
  • options: An associative array of key-value pairs, where the value is what should be displayed to the user, and the key is what should be submitted if that value is chosen.
  • hint: a suggestion on how this should be rendered. Possible values are radio or select. These do not need to correspond strictly to an html <select> tag or list of radio buttons, however the hint will correspond to what the user is more familiar with seeing on their usual bank login screen. A radio suggestion would be best displayed so that the user can see all options, and clicking on one may auto-submit to go on to the next step. A select suggestion may mean the options are more appropriately displayed in a select or combo box.
set A set is a container for a group of fields which are related, and may be more appropriately displayed as a group. The set itself does not necessarily require any specific rendering.

Attributes
  • subElements: an array of MFA Fields - these could be a mixture of any of the above types (including possibly further set elements, although this is unlikely).
javascript Some javascript code to be included on the page, in an html context. This is usually for convenience of the customer, such as automatically moving the cursor to the next input. For security or other reasons, you may wish to ignore these fields. However, there may be cases where equivalent work functionality will be required, through custom development.

Additional MFA Request Examples

Centrelink example

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

HSBC (Security Device)

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

HSBC (Passwords)

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

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

Bank specific examples

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

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

HSBC (passwords):
  • memorableAnswer (password): Standard password field
  • RCCField (set/passwords): A set of password fields, only those that are active/not optional will have ID’s.
  • javascript: Runs to allow auto selection of the current password field (not required)
  • To submit the memorableAnswer must be in the memorableAnswer field and characters in each of their respective RCCFields with an ID.
HSBC (device):
  • memorableAnswer (password): Password field
  • idv_OtpCredential (password): Password field where the user enters the password sent to their HSBC device. The sending of the code is automatically processed with the login step.

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

MFA Response

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

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

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

DESCRIPTION

MFA Response Example (CBA Bank)

{
  "netcode": "XXX",
  "user_token": "60...de92b"
}
<xml>
  <netcode>XXX</netcode>
  <user_token>60...de92b</user_token>
</xml>

MFA Response Example (HSBC Bank - with Password)

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

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

FUNCTION

Request PartValue
TypePOST
URL/mfa

REQUEST HEADER

NameRequiredValue
X-API-KEYYour API key (see API Keys)
Content-TypeThe format of your request data (see Input Data)
AcceptA 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

NameRequiredValue
user_tokenThis 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:

  1. Use the Initialise Client-Side Retrieval Request from your application to generate a guid and user_token.
  2. Provide a web page to your customer that contains the functionality to make requests to the BankStatements API. These requests will use the single use guid and user_token retrieved via step 1.
  3. 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.
  4. 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.
  5. 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.
  6. 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.

Client-Side API Process

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

TypePOST
URL/init_cs_request

REQUEST HEADER

NameRequiredValue
X-API-KEYYour API key (see API Keys)
Content-TypeThe data format of your request (see Request Data Format)
AcceptThe desired data format of the response (see Response Data Format)

REQUEST BODY

NameRequiredValue
referral_codeA 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

TypePOST
URL/cs_preload/guid

REQUEST HEADER

NameRequiredValue
Content-TypeThe data format of your request (see Request Data Format)
AcceptThe desired data format of the response (see Response Data Format)
X-OUTPUT-VERSIONThe desired version of this API function to implement (see API Versions)

Supported values:
  • 20160527
  • 20170401
X-USER-TOKENThis 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

TypePOST
URL/cs_login/guid

REQUEST HEADER

NameRequiredValue
Content-TypeThe data format of your request (see Request Data Format)
AcceptThe desired data format of the response (see Response Data Format)
X-OUTPUT-VERSIONThe desired version of this API function to implement (see API Versions)

Supported values:
  • 20160527
  • 20170401
X-USER-TOKENThis 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

TypePOST
URL/cs_mfa/guid

REQUEST HEADER

NameRequiredValue
Content-TypeThe data format of your request (see Request Data Format)
AcceptThe desired data format of the response (see Response Data Format)
X-OUTPUT-VERSIONThe desired version of this API function to implement (see API Versions)

Supported values:
  • 20160527
  • 20170401
X-USER-TOKENThis 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

TypePOST
URL/cs_export/guid

REQUEST HEADER

NameRequiredValue
Content-TypeThe data format of your request (see Request Data Format)
AcceptThe desired data format of the response (see Response Data Format)
X-OUTPUT-VERSIONThe desired version of this API function to implement (see API Versions)

Supported values:
  • 20160527
  • 20170401
X-USER-TOKENThis 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

TypePOST
URL/cs_login_fetch_all/guid

REQUEST HEADER

NameRequiredValue
Content-TypeThe data format of your request (see Request Data Format)
AcceptThe desired data format of the response (see Response Data Format)
X-OUTPUT-VERSIONThe desired version of this API function to implement (see API Versions)

Supported values:
  • 20160527
  • 20170401
X-USER-TOKENThis 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:

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:

  1. 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).
  2. Handle the login response which, on success, will be a MFA Request. On failure it could include an error or timeout response.
  3. Submit the MFA Response.
  4. 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.
  5. (Optional) Make a request for a Centrelink document.

Centrelink API Process

An alternate process for retrieving Centrelink data is as follows:

  1. 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).
  2. Handle the login response which, on success, will be a MFA Request. On failure it could include an error or timeout response.
  3. Submit the MFA Response.
  4. 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.
  5. 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.
  6. (Optional) Make a request for a Centrelink document.

Centrelink API Process

DESCRIPTION

Check the availability status of the Centrelink service.

FUNCTION

Request PartValue
TypeGET
URL/centrelink_status

REQUEST HEADER

NameRequiredValue
X-API-KEYYour API key (see API Keys)
Content-TypeThe data format of your request (see Request Data Format)
AcceptThe desired data format of the response (see Response Data Format)

RETURN RESPONSE

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

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

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

Response (Centrelink service is available):

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

Response (Centrelink service is not available):

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

Request (Replace with valid credentials):

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

DESCRIPTION

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

FUNCTION

Request PartValue
TypePOST
URL/centrelink_login

REQUEST HEADER

NameRequiredValue
X-API-KEYYour API key (see API Keys)
Content-TypeThe data format of your request (see Request Data Format)
AcceptThe desired data format of the response (see Response Data Format)

REQUEST BODY

NameRequiredValue
credentialsThis must be present and must contain both the username and password for the user’s login service provider (See information below).

Attributes
  • username: The end user’s username.
  • password: The end user’s password.
serviceThis 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_codeA 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.

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 PartValue
TypePOST
URL/centrelink_login_only

REQUEST HEADER

NameRequiredValue
X-API-KEYYour API key (see API Keys)
Content-TypeThe data format of your request (see Request Data Format)
AcceptThe desired data format of the response (see Response Data Format)

REQUEST BODY

NameRequiredValue
credentialsThis must be present and must contain both the username and password for the user’s login service provider (See information below).

Attributes
  • username: The end user’s username.
  • password: The end user’s password.
serviceThis 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_codeA 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.

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 PartValue
TypePOST
URL/centrelink_mfa

REQUEST HEADER

NameRequiredValue
X-API-KEYYour API key (see API Keys)
Content-TypeThe data format of your request (see Request Data Format)
AcceptThe desired data format of the response (see Response Data Format)

REQUEST BODY

NameRequiredValue
user_tokenThis should be the user_token value from the previously received response.
fieldsThis must be present and must contain all the individual field objects that were sent in the MFA Request. This ensures that all the information that was requested in the MFA Request can be returned as part of the MFA Response.

Note that the number of <field> objects returned by the API is subject to change, and so your application should not hard-code any assumptions about the number of fields being returned based on the current state of the API. Additionally, the fields of type hidden will generally contain the value that must be returned as part of the MFA Response. The API may be updated in the future to not include these as part of future MFA Requests.

Attributes
  • field: There must always be at least one, but there could be multiple required.
    • id: The id of the corresponding MFA Field Object from the MFA Request.
    • value: The value to be submitted (which may come from a hidden Field Type in the MFA Request).

RETURN RESPONSE

Response:

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

Response (Example - no data available):

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

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

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

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

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

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

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

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

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

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

Request:

{
  "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 PartValue
TypePOST
URL/centrelink_data

REQUEST HEADER

NameRequiredValue
X-API-KEYYour API key (see API Keys)
Content-TypeThe data format of your request (see Request Data Format)
AcceptThe 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.

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 PartValue
TypePOST
URL/centrelink_documents

REQUEST HEADER

NameRequiredValue
X-API-KEYYour API key (see API Keys)
Content-TypeThe data format of your request (see Request Data Format)
AcceptThe desired data format of the response (see Response Data Format)

REQUEST BODY

Name Required Value
user_token This should be the user_token value from the previously received response
document The document type that you want to retrieve.

Available document types:
  • generated_data: The document that is automatically created by BankStatements of the raw data that was retrieved. (BankStatements branded)
  • income_statement: The Centrelink Income Statement (Centrelink branded)

RETURN RESPONSE

Response:

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

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

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.

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 PartValue
TypePOST
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.

NameRequiredValue
X-API-KEYYour API key (see API Keys)
Content-TypeThe data format of your request (see Request Data Format)
AcceptThe desired data format of the response (see Response Data Format)
X-USER-TOKENThis may be a required parameter if the user_token is not specified as part of the URL query string.

REQUEST BODY

NameRequiredValue
user_tokenThis 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.

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:

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:

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