BankFeeds Introduction
The BankFeeds product allows for bank statement data to be initially retrieved and subsequently refreshed from customer’s bank accounts. BankFeeds exposes its functionality via an Application Programming Interface (API) in order to support the development of third party applications that can interact with BankFeeds. These third party applications can then store customer credentials and facilitate the retrieval of the customer’s data.
This document describes how to integrate with the BankFeeds API.
Getting Started
In order to interact with the BankFeeds API you will need to:
- Determine the base API URL for your API requests.
- Obtain an API Key specific to the API environment you will be using.
- Determine the data format that you will use to send API requests, and the data format you will use when receiving API responses.
- Begin testing your application’s integration with the API.
API URL
The BankFeeds API is available via a production environment (i.e https://api.bankfeeds.com.au/
) and a test environment (i.e. https://apitest.bankfeeds.com.au/
). All API calls must include the API version as the first part of the URL’s path, and this then forms the base URL. For example:
https://api.bankfeeds.com.au/v1/
https://apitest.bankfeeds.com.au/v1/
The request endpoints for API functions that are specified in this document are relative to these base urls.
API Versions
The API is versioned, so that changes and updates to the API do not cause compatibility issues with existing integrations. The API version is determined by the number in the API URL. The current version is v1
.
Backwards compatible changes to the API may be introduced to an API version over time, such as adding new endpoints or optional fields to existing endpoints etc. These changes will be announced and documented in order to allow existing clients to be able to take advantage of newer API functionality.
It is possible to interact with specific versions of API functions by using the custom HTTP header X-OUTPUT-VERSION
, which requires a value of a date in the format yyyymmdd
(i.e. 20160527
). This allows integration with a specific version of an API function. When this HTTP header is not provided, then the base API function will be used as a default. This means that newer functionality and/or response formats must be explicitly requested.
For more information regarding the available customer data formats see here.
API Keys
API keys are used to authenticate your application with the BankFeeds API, and identify that the requests made are
associated with your organisation/account. All requests to the API must include your API key. This must be included
as a custom HTTP header called X-API-KEY
, and the value being your actual API key. Please contact us when you require
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. Different keys will be used 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
Data sent to the API from your application can be sent in one of the following formats. In order to communicate the format of the data being sent in the request, it is necessary to include a Content-Type
HTTP header with the value reflecting the data format being used. If the Content-Type
HTTP header is omitted then the API will treat the request as being in JSON format.
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 specify the format of the data being returned from the request, it is necessary to include an Accept
HTTP header with the value reflecting the data format desired. 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 |
Customers
The basic data storage object in BankFeeds is a customer. Currently a customer can have only one set of credentials for an individual bank. If your users have credentials for more than one bank/institution, then you will need to create multiple BankFeeds customers for a single one of your users, and manage the association between your users and their corresponding BankFeeds customer object in your application.
See Create Customer and Customer Initialisation Helper.
Customer Id
Each customer is referenced by a universally unique identifier (UUID), referred to as the customerId
. This is presented as a 36 character string such as 604fc88b-a6f5-4c68-a7c7-308962358c58 (i.e. in the format {8}-{4}-{4}-{4}-{12}). This will be constant for the life of the customer, and must be provided in every request relating to that customer.
Encryption Keys
With every customer you create, we will provide you with an encryption key, referred to as the encryptionKey
. BankFeeds cannot access the user’s accounts or data without this key so it must send be provided along with the customerId
for any request relating to a customer. If this key is lost, then it is not possible for us to provide it to you again. In this case, you would need to create another customer object for the user in BankFeeds which would require the user to re-enter their credentials.
For added security, this encryptionKey
will be changed regularly as you access the API for a specific customer. You must save the updated encryptionKey
when it is provided in an API response, or you will lose access to the user’s account, and they will be required to create another customer object for the user.
The encryptionKey
is 32 bytes, and is transmitted in base64 encoded format. Your application should allow 44 characters to store this data. Also be aware that forward slashes may be escaped with a backslash in JSON. Your JSON parser should strip out this backslashes for you. If not, these backslashes, if present, may be safely removed.
Testing
Testing of your application’s integration with BankFeeds should be performed in the test API environment (see API URLs).
To assist with testing, BankFeeds 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
A bank has been set up in the test environment called “Bank of Statements” that can be used when creating customers in BankFeeds. 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 or password then the response will be an error message.
Credential Name | Value |
---|---|
institution | bank_of_statements |
username | 12345678 |
password | TestMyMoney |
This account will return some semi randomised data when retrieving accounts and retrieving account data.
Note that you re-use these same credentials with the Create Customer function in order to create multiple customers for testing.
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 creating customers in BankFeeds. It will allow you to test the basic/standard scenarios of the API functions, with the addition of MFA steps. This will allow you to replicate the MFA request/response process that is used by various institutions.
Credential Name | Value |
---|---|
institution | bank_of_mfa |
The credentials below can be used to simulate different types of MFA, per the descriptions. For each test account described, a credential named with-mfa
should be supplied with the value of with
. This will enable the MFA functionality and cause a MFA response to be returned. For any other value, MFA will not be used.
AVAILABLE CREDENTIALS
- A single text field, entering a code from a token
Credential Name | Value |
---|---|
username | cba |
password | cba |
with-mfa | with |
- Selecting between a set of account profiles
Credential Name | Value |
---|---|
username | westpac |
password | westpac |
with-mfa | with |
- Two text fields - entering a password and a value from a token
Credential Name | Value |
---|---|
username | hsbc-device |
password | hsbc-device |
with-mfa | with |
- Entering a password, and then three select characters from a secondary password
Credential Name | Value |
---|---|
username | hsbc-passwords |
password | hsbc-passwords |
with-mfa | with |
- Entering a password, and then enter code from digipass device (rabobank)
Credential Name | Value |
---|---|
username | rabo |
password | rabo |
with-mfa | with |
- Entering a username and MFA without password (rabobank)
Credential Name | Value |
---|---|
username | rabo |
with-mfa | with |
- Veifying push notification (bendigo)
Credential Name | Value |
---|---|
username | bendigo |
password | bendigo |
with-mfa | with |
- Veifying push notification (macquarie)
Credential Name | Value |
---|---|
username | macquarie |
password | macquarie |
with-mfa | with |
- MFA response with HTML hidden field
Credential Name | Value |
---|---|
username | mfaExampleHtmlHidden |
password | mfaExampleHtmlHidden |
with-mfa | with |
- MFA response with button
Credential Name | Value |
---|---|
username | mfaExampleButton |
password | mfaExampleButton |
with-mfa | with |
- MFA response with image
Credential Name | Value |
---|---|
username | mfaExampleImage |
password | mfaExampleImage |
with-mfa | with |
- MFA response with options
Credential Name | Value |
---|---|
username | mfaExampleOptions |
password | mfaExampleOptions |
with-mfa | with |
- MFA response for multiple step MFA with profile selection
Credential Name | Value |
---|---|
username | mfaAndProfile |
password | mfaAndProfile |
with-mfa | with |
Optional MFA Test Account Details
There are a few banks where some users may be required to enter a value from an MFA device together with their other credentials (username and password), rather than on a second form as is the case for the MFA described above. We have a separate test bank available to test this, the Bank of Optional MFA.
Bank Name | Bank Slug |
---|---|
Bank of Optional MFA | bank_of_optmfa |
Two sets of credentials are available for this bank - one which requires the MFA value, and one which must not be used with an mfa value.
Credential Name | Value |
---|---|
username | with |
password | with |
date (MFA field) | Today's date in Ymd format. Eg 20170718 |
Credential Name | Value |
---|---|
username | without |
password | without |
date (MFA field) | <blank> |
Captcha Test Account Details
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 BankFeeds, in order to test this scenario with the API functions.
Credential Name | Value |
---|---|
institution | bank_of_captcha |
username | 12345678 |
password | TestMyMoney |
The example response from the authentication request will be a Request for Additional Information, that will provide a base64 encoded image (with the value D49ZHN
). This value can be sent back as part of a Followup Request.
Testing Error Conditions
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 (and so a customer will be created), but any attempt to export transactions will cause an error.
Credential Name | Value |
---|---|
institution | bank_of_statements |
username | error |
password | error |
API Functions
This section describes the available functions provided by the BankFeeds API.
Verify API Status
Response:
{
"status": true
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<status>1</status>
</xml>
DESCRIPTION
Checks if the API is online and functioning.
FUNCTION
Request Part | Value |
---|---|
Type | GET |
URL | /verify |
REQUEST HEADER
Name | Required | Value |
---|---|---|
X-API-KEY | Your API key (see API Keys) | |
Content-Type | The data format of your request (see Request Data Format) | |
Accept | The desired data format of the response (see Response Data Format) |
RETURN RESPONSE
Will return status of true
if the API is online and working. Any other response indicate’s that the API is offline (i.e. if you receive a network timeout error, or other connectivity error).
List Institutions
Response:
{
"institutions":
[
{
"slug": "anz",
"name": "ANZ",
"credentials":
[
{
"name": "Customer Registration Number",
"fieldID": "username",
"type": "TEXT",
"description": "",
"values": "",
"keyboardType": "number"
},
{
"name": "Password",
"fieldID": "password",
"type": "password",
"description": "",
"values": "",
"keyboardType": "default"
}
],
"status": "",
"searchable": "1",
"display": "1",
"searchVal": "anzaustralianewzealandaustraliaandnewzealandbankinggroup",
"region": "au",
"export_with_password": 0,
"estatements_supported": 1,
"transaction_listings_supported": "1",
"requires_preload": "0",
"requires_mfa": "0",
"updated_at": "2014-11-25 16:53:39",
"max_days": "120"
},
{
"continues":"..."
}
],
"user_token": "88ms8g90n19lli6l7"
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<institutions>
<institution>
<slug>adcu</slug>
<name>Australian Defence Credit Union</name>
<credentials>
<credential>
<name>Member Number</name>
<fieldID>username</fieldID>
<type>TEXT</type>
<description></description>
<values></values>
</credential>
<credential>
<name>Access Code</name>
<fieldID>password</fieldID>
<type>password</type>
<description></description>
<values></values>
</credential>
</credentials>
<status></status>
<searchable>1</searchable>
<display>0</display>
<searchVal>australiandefencecreditunionadcu</searchVal>
<region>au</region>
<export_with_password>0</export_with_password>
<estatements_supported>1</estatements_supported>
<transaction_listings_supported>1</transaction_listings_supported>
<requires_preload>0</requires_preload>
<requires_mfa>0</requires_mfa>
<updated_at>2015-05-25 11:58:55</updated_at>
<max_days>180</max_days>
</institution>
<continues>
</continues>
<institutions>
</xml>
DESCRIPTION
Get a list of all the supported institutions for which customer data can be retrieved.
FUNCTION
Request Part | Value |
---|---|
Type | GET |
URL | /institutions |
REQUEST HEADER
Name | Required | Value |
---|---|---|
X-API-KEY | Your API key (see API Keys) | |
Content-Type | The data format of your request (see Request Data Format) | |
Accept | The desired data format of the response (see Response Data Format) |
RETURN RESPONSE
An array of all currently supported financial institutions, and all relevant information about them. Specifically, the response will describe the credential information that is required to log in with that institution, and should be used when Creating Customers.
Create Customer
1 - Request:
{
"name":"A C Holder",
"credentials": {
"institution": "bank_of_statements",
"username": "12345678",
"password": "TestMyMoney"
},
"userRef": "my-ref",
"generateRawFile": true
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<name>A C Holder</name>
<credentials>
<institution>bank_of_statements</institution>
<username>12345678</username>
<password>TestMyMoney</password>
</credentials>
<userRef>my-ref</userRef>
<generateRawFile>true</generateRawFile>
</xml>
1 - Response:
{
"customerId":"56f0...7164",
"encryptionKey":"ewP7...U9SY="
}
<xml>
<customerId>56f0...7164</customerId>
<encryptionKey>ewP7...U9SY=</encryptionKey>
</xml>
2 - MFA Customer Example Request:
{
"name":"A C Holder",
"credentials": {
"institution": "bank_of_mfa",
"username": "cba",
"password": "cba",
"with-mfa": "with"
},
"userRef": "my-ref",
"generateRawFile": true
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<name>A C Holder</name>
<credentials>
<institution>bank_of_mfa</institution>
<username>cba</username>
<password>cba</password>
<with-mfa>with</with-mfa>
</credentials>
<userRef>my-ref</userRef>
<generateRawFile>true</generateRawFile>
</xml>
2 - MFA Customer Example Response (MFA Request for Additional Information):
{
"type": "additionalInformationNeeded",
"title": "NetCode token required",
"fields": [
{
"type": "header",
"text": "Please Enter Your NetCode (123456)"
},
{
"type": "instructions",
"text": "How to use your security Token"
},
{
"type": "set",
"text": "",
"subElements": [
{
"type": "instructions",
"text": "1. Press the button on your token"
},
{
"type": "instructions",
"text": "2. A unique NetCode will be displayed on the token's screen"
},
{
"type": "instructions",
"text": "3. Enter your 6 digit NetCode below"
}
]
},
{
"type": "input",
"text": "",
"fieldID": "netcode",
"htmlAttrs": {
"autocomplete": "off"
}
}
],
"submitTo": "/v1/followupRequest/eyJ0...LVE",
"expiresIn": null,
"customer": {
"customerId": "56f0...7164",
"encryptionKey": "ewP7...U9SY="
}
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<type>additionalInformationNeeded</type>
<title>NetCode token required</title>
<fields>
<field>
<type>header</type>
<text>Please Enter Your NetCode (123456)</text>
</field>
<field>
<type>instructions</type>
<text>How to use your security Token</text>
</field>
<field>
<type>set</type>
<text/>
<subElements>
<subElement>
<type>instructions</type>
<text>1. Press the button on your token</text>
</subElement>
<subElement>
<type>instructions</type>
<text>2. A unique NetCode will be displayed on the token's screen</text>
</subElement>
<subElement>
<type>instructions</type>
<text>3. Enter your 6 digit NetCode below</text>
</subElement>
</subElements>
</field>
<field>
<type>input</type>
<text/>
<fieldID>netcode</fieldID>
<htmlAttrs>
<autocomplete>off</autocomplete>
</htmlAttrs>
</field>
</fields>
<submitTo>/v1/followupRequest/eyJ0...LVE</submitTo>
<expiresIn/>
<customer>
<customerId>56f0...7164</customerId>
<encryptionKey>ewP7...U9SY=</encryptionKey>
</customer>
</xml>
2 - MFA Customer Example Response (Original Data Version)
{
"accounts": {
"bank_of_mfa": {
"accounts": [
{
"accountHolder": "Mary Jones",
"name": "Transaction Account",
"accountNumber": "456789",
"id": 0,
"bsb": "123-456",
"balance": "123.45",
"available": "123.45",
"statementData": {
"details": [
{
"dateObj": {
"date": "2018-05-01 00:00:00.000000",
"timezone_type": 3,
"timezone": "Australia/Adelaide"
},
"date": "01-05-2018",
"text": "Interest - current rate is 1.05%",
"notes": null,
"amount": 2.45,
"type": "Credit",
"balance": "3123.45",
"tags": [
"Income"
]
}
]
},
"institution": "Bank of MFA",
"accountType": "transaction"
}
]
}
},
"user_token": "k6lfos...6lihf",
"referral_code": "56f0...7164",
"reportsLink": "/v1/reports/eyJ0...gPg",
"customer": {
"customerId": "56f0...7164",
"encryptionKey": "ewP7...U9SY="
}
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<accounts>
<bank_of_mfa>
<accounts>
<account>
<accountHolder>Mary Jones</accountHolder>
<name>Transaction Account</name>
<accountNumber>456789</accountNumber>
<id>0</id>
<bsb>123-456</bsb>
<balance>123.45</balance>
<available>123.45</available>
<statementData>
<details>
<detail>
<dateObj>
<date>2018-04-29 00:00:00.000000</date>
<timezone_type>3</timezone_type>
<timezone>Australia/Adelaide</timezone>
</dateObj>
<date>29-04-2018</date>
<text>Interest - current rate is 1.05%</text>
<notes/>
<amount>2.45</amount>
<type>Credit</type>
<balance>123.45</balance>
<tags>
<tag>Income</tag>
</tags>
</detail>
</details>
</statementData>
<institution>Bank of MFA</institution>
<accountType>credit card</accountType>
</account>
</accounts>
</bank_of_mfa>
</accounts>
<user_token>k6lfos...6lihf</user_token>
<referral_code>56f0...7164</referral_code>
<reportsLink>/v1/reports/eyJ0...gPg</reportsLink>
<customer>
<customerId>56f0...7164</customerId>
<encryptionKey>ewP7...U9SY=</encryptionKey>
</customer>
</xml>
2 - MFA Customer Example Response (Data Version 20160527)
{
"reference": "4e9d34da-caa0-4109-9c57-0adafe6821ae",
"submissionTime": "2018-05-01T15:29:00",
"bankData": {
"bankName": "Bank of MFA",
"bankSlug": "bank_of_mfa",
"bankAccounts": [
{
"id": 0,
"accountType": "transaction",
"accountHolder": "Mary Jones",
"accountName": "Transaction Account",
"bsb": "123-456",
"accountNumber": "456789",
"currentBalance": "123.45",
"availableBalance": "123.45",
"transactions": [
{
"date": "2018-04-30",
"text": "Interest - current rate is 1.05%",
"amount": 2.45,
"type": "",
"balance": "123.45",
"tags": [
{
"thirdParty": "Other Credits"
},
{
"category": "All Other Credits"
},
{
"creditDebit": "credit"
}
]
}
],
"statementSummary": {
"openingBalance": "-3485.90",
"totalCredits": "17967.18",
"totalDebits": "-14357.83",
"closingBalance": "123.45",
"minBalance": "-4929.25",
"minDayEndBalance": "-4929.25",
"daysInNegative": 155,
"searchPeriodStart": "2017-11-02",
"searchPeriodEnd": "2018-04-30",
"transactionsStartDate": "2017-11-02",
"transactionsEndDate": "2018-04-30"
}
}
],
"userAddress": {
"text": ""
}
},
"user_token": "k6lfos...6lihf",
"referral_code": "56f0...7164",
"reportsLink": "/v1/reports/eyJ0...gPg",
"customer": {
"customerId": "56f0...7164",
"encryptionKey": "ewP7...U9SY="
}
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<reference>86423772-caac-4ccc-879a-77ca39cc44e0</reference>
<submissionTime>2018-05-01T15:17:00</submissionTime>
<bankData>
<bankName>Bank of MFA</bankName>
<bankSlug>bank_of_mfa</bankSlug>
<bankAccounts>
<bankAccount>
<id>0</id>
<accountType>transaction</accountType>
<accountHolder>Mary Jones</accountHolder>
<accountName>Transaction Account</accountName>
<bsb>123-456</bsb>
<accountNumber>456789</accountNumber>
<currentBalance>123.45</currentBalance>
<availableBalance>123.45</availableBalance>
<transactions>
<transaction>
<date>2018-05-01</date>
<text>Interest - current rate is 1.05%</text>
<amount>2.45</amount>
<type/>
<balance>123.45</balance>
<tags>
<tag>
<thirdParty>Other Credits</thirdParty>
</tag>
<tag>
<category>All Other Credits</category>
</tag>
<tag>
<creditDebit>credit</creditDebit>
</tag>
</tags>
</transaction>
</transactions>
<statementSummary>
<openingBalance>-5757.05</openingBalance>
<totalCredits>17464.73</totalCredits>
<totalDebits>-11584.23</totalDebits>
<closingBalance>123.45</closingBalance>
<minBalance>-6031.58</minBalance>
<minDayEndBalance>-6031.58</minDayEndBalance>
<daysInNegative>152</daysInNegative>
<searchPeriodStart>2017-11-02</searchPeriodStart>
<searchPeriodEnd>2018-05-01</searchPeriodEnd>
<transactionsStartDate>2017-11-02</transactionsStartDate>
<transactionsEndDate>2018-05-01</transactionsEndDate>
</statementSummary>
</bankAccount>
</bankAccounts>
<userAddress>
<text/>
</userAddress>
</bankData>
<user_token>k6lfos...6lihf</user_token>
<referral_code>56f0...7164</referral_code>
<reportsLink>/v1/reports/eyJ0...gPg</reportsLink>
<customer>
<customerId>56f0...7164</customerId>
<encryptionKey>ewP7...U9SY=</encryptionKey>
</customer>
</xml>
2 - MFA Customer Example Response (Data Version 20170401)
{
"dataVersion": "20170401",
"reference": "6f0...7164",
"submissionTime": "2018-05-01T14:35:00",
"bankData": {
"bankName": "Bank of MFA",
"bankSlug": "bank_of_mfa",
"bankAccounts": [
{
"id": 0,
"accountType": "transaction",
"accountHolder": "Mary Jones",
"accountName": "Transaction Account",
"bsb": "123-456",
"accountNumber": "456789",
"currentBalance": "123.45",
"availableBalance": "123.45",
"transactions": [
{
"date": "2018-05-01",
"text": "Interest - current rate is 1.05%",
"amount": 2.45,
"type": "",
"balance": "123.45",
"tags": [
{
"thirdParty": "Other Credits"
},
{
"category": "All Other Credits"
},
{
"creditDebit": "credit"
}
]
}
],
"statementSummary": {
"openingBalance": "-6856.06",
"totalCredits": "18467.43",
"totalDebits": "-11487.92",
"closingBalance": "123.45",
"minBalance": "-7099.40",
"minDayEndBalance": "-7084.50",
"daysInNegative": 107,
"searchPeriodStart": "2017-11-02",
"searchPeriodEnd": "2018-05-01",
"transactionsStartDate": "2017-11-02",
"transactionsEndDate": "2018-05-01"
}
}
],
"userAddress": {
"text": ""
}
},
"decisionMetrics": [],
"user_token": "k6lfos...6lihf",
"referral_code": "56f0...7164",
"reportsLink": "/v1/reports/eyJ0...gPg",
"customer": {
"customerId": "56f0...7164",
"encryptionKey": "ewP7...U9SY="
}
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<dataVersion>20170401</dataVersion>
<reference>6f0...7164</reference>
<submissionTime>2018-05-01T15:04:00</submissionTime>
<bankData>
<bankName>Bank of MFA</bankName>
<bankSlug>bank_of_mfa</bankSlug>
<bankAccounts>
<bankAccount>
<id>0</id>
<accountType>transaction</accountType>
<accountHolder>Mary Jones</accountHolder>
<accountName>Transaction Account</accountName>
<bsb>123-456</bsb>
<accountNumber>456789</accountNumber>
<currentBalance>123.45</currentBalance>
<availableBalance>123.45</availableBalance>
<transactions>
<transaction>
<date>2018-05-01</date>
<text>Interest - current rate is 1.05%</text>
<amount>2.45</amount>
<type/>
<balance>123.45</balance>
<tags>
<tag>
<thirdParty>Other Credits</thirdParty>
</tag>
<tag>
<category>All Other Credits</category>
</tag>
<tag>
<creditDebit>credit</creditDebit>
</tag>
</tags>
</transaction>
</transactions>
<statementSummary>
<openingBalance>-7910.75</openingBalance>
<totalCredits>18987.80</totalCredits>
<totalDebits>-10953.60</totalDebits>
<closingBalance>123.45</closingBalance>
<minBalance>-8651.91</minBalance>
<minDayEndBalance>-8647.03</minDayEndBalance>
<daysInNegative>178</daysInNegative>
<searchPeriodStart>2017-11-02</searchPeriodStart>
<searchPeriodEnd>2018-05-01</searchPeriodEnd>
<transactionsStartDate>2017-11-02</transactionsStartDate>
<transactionsEndDate>2018-05-01</transactionsEndDate>
</statementSummary>
</bankAccount>
</bankAccounts>
<userAddress>
<text/>
</userAddress>
</bankData>
<decisionMetrics/>
<user_token>k6lfos...6lihf</user_token>
<referral_code>56f0...7164</referral_code>
<reportsLink>/v1/reports/eyJ0...gPg</reportsLink>
<customer>
<customerId>56f0...7164</customerId>
<encryptionKey>ewP7...U9SY=</encryptionKey>
</customer>
</xml>
3 - Optional MFA Example Request:
{
"name":"A C Holder",
"credentials": {
"institution": "bank_of_optmfa",
"username": "with",
"password": "with",
"date": "20180501"
}
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<name>A C Holder</name>
<credentials>
<institution>bank_of_optmfa</institution>
<username>with</username>
<password>with</password>
<date>20180501</date>
</credentials>
</xml>
3 - Optional MFA Example Response:
{
" See the data version responses for '2 - MFA Customer Example Response'"
}
<!-- See the data version responses for "2 - MFA Customer Example Response" -->
4 - List Only Example Request:
{
"name":"A C Holder",
"credentials": {
"institution": "bank_of_statements",
"username": "12345678",
"password": "TestMyMoney"
},
"listOnly": true
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<name>A C Holder</name>
<credentials>
<institution>bank_of_statements</institution>
<username>12345678</username>
<password>TestMyMoney</password>
</credentials>
<listOnly>true</listOnly>
</xml>
4 - List Only Example Response:
{
"accounts": [
{
"accountHolder": "Mary Jones",
"name": "Transaction Account",
"accountNumber": "456789",
"id": 0,
"bsb": "123-456",
"balance": "123.45",
"available": "123.45",
"accountType": "transaction"
},
{
"accountHolder": "Mary Jones and Tom Jones",
"name": "Savings Account",
"accountNumber": "945315",
"id": 1,
"bsb": "123-456",
"balance": "3123.45",
"available": "3123.45",
"interestRate": "3.89",
"accountType": "savings"
},
{
"accountHolder": "Mary Jones and Tom Jones",
"name": "Credit Card",
"accountNumber": "XXXX XXXX XXXX 7654",
"id": 2,
"bsb": "",
"balance": "-3193.45",
"available": "15553.55",
"interestRate": "13.99",
"accountType": "credit card"
}
],
"user_token": "4a7e30456efbdda658b15df03f38dcee",
"referral_code": "07fd...dae1",
"customer": {
"customerId": "07fd...dae1",
"encryptionKey": "qjha...uzw="
},
"dataRequestLink": "/v1/customer/data/eyJ0eX...YzE0hE_G_GReJrnzx4c"
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<accounts>
<account>
<accountHolder>Mary Jones</accountHolder>
<name>Transaction Account</name>
<accountNumber>456789</accountNumber>
<id>0</id>
<bsb>123-456</bsb>
<balance>123.45</balance>
<available>123.45</available>
<accountType>transaction</accountType>
</account>
<account>
<accountHolder>Mary Jones and Tom Jones</accountHolder>
<name>Savings Account</name>
<accountNumber>945315</accountNumber>
<id>1</id>
<bsb>123-456</bsb>
<balance>3123.45</balance>
<available>3123.45</available>
<interestRate>3.89</interestRate>
<accountType>savings</accountType>
</account>
<account>
<accountHolder>Mary Jones and Tom Jones</accountHolder>
<name>Credit Card</name>
<accountNumber>XXXX XXXX XXXX 7654</accountNumber>
<id>2</id>
<bsb/>
<balance>-3193.45</balance>
<available>15553.55</available>
<interestRate>13.99</interestRate>
<accountType>credit card</accountType>
</account>
</accounts>
<user_token>4a7e30456efbdda658b15df03f38dcee</user_token>
<referral_code>07fd...dae1</referral_code>
<customer>
<customerId>07fd...dae1</customerId>
<encryptionKey>qjha...uzw=</encryptionKey>
</customer>
<dataRequestLink>/v1/customer/data/eyJ0eX...YzE0hE_G_GReJrnzx4c</dataRequestLink>
</xml>
DESCRIPTION
Create a new customer in BankFeeds and store the user’s credentials for an individual institution. See Customer Initialisation Helper as an alternative.
FUNCTION
Request Part | Value |
---|---|
Type | POST |
URL | /customer/create |
REQUEST HEADER
Name | Required | Value |
---|---|---|
X-API-KEY | Your API key (see API Keys) | |
Content-Type | The data format of your request (see Request Data Format) | |
Accept | The desired data format of the response (see Response Data Format) | |
X-OUTPUT-VERSION | The desired version of this API function to implement (see API Versions) Supported values:
|
REQUEST BODY
Name | Required | Value |
---|---|---|
name | The name of the account holder. | |
credentials | This must be present and must contain all the individual credential objects that were specified in the response from the List Institution request. This means that each field of the credentials element used in the request must match the fieldID fields returned in the response from the List Institution request.Example Attributes
| |
userRef | The User Reference tag to be associated with the customer. This will only be used if the Users feature has been activated on your account. | |
generateRawFile | Default is false . If set to true then a file containing the raw bank data will also be supplied with the files downloaded through the reportsLink URL.Note:
| |
listOnly | Default is false . If explicitly set to true then the response returned from this function will be similar to the output of a list customer accounts function.
For example, an account listing will always be included in the response, and in the case of an MFA login, no data will be pulled from the accounts, however a dataRequestLink will also be returned so even in the case of an MFA login additional queries can be made until the dataRequestLink expires. See the specific examples for more information. |
RETURN RESPONSE
Following are example scenarios that can occur after a customer create request has been sent by your application to the BankFeeds API.
- No MFA. This is the most common case. If there are no optional MFA credential fields for this institution, or an optional MFA value is not provided/required for this user, and there is no secondary MFA step, then the response will contain the
customerID
andencryptionKey
for this customer in the BankFeeds system. You will need to store these values to use in subsequent requests. - Secondary MFA. If there are no optional MFA credential fields for this institution, or an optional MFA value is not provided/required for this user, but the bank does require a secondary MFA step, then the response returned by the API will be a Request for additional information. It will be necessary to submit the required information back to the API so that the customer create process can be completed successfully. Some examples are provided in this section, but please also refer to Retrieve Customer Data for non truncated examples.
- Optional MFA. If the request is sent with an optional MFA credential field, then the response will contain the full account data (which will also include the
customerID
andencryptionKey
, see the example response for the Data request for more detail) for the customer. This is due to the nature of MFA tokens typically being temporary, and therefore BankFeeds is not able to store them. BankFeeds will therefore return all the customer’s data as a convenience when creating the customer (i.e. only if that customer requires MFA). When acustomer/data
request is made, the response will be a Request for additional information requesting the Optional MFA field. - List Only. If this optional parameter is included in the request and set to
true
, then the response will be a list of the customer’s available accounts (see the example response for List Customer Accounts). If this optional parameter is used for a customer that requires MFA (or used with Optional MFA credentials), then instead of the account data being returned in the response, the response will simply list the available accounts. - Error. In the event of an unsuccessful request, an error response may be returned.
In the above descriptions, the term “secondary MFA step” refers to the user entering a piece of MFA data (SMS Code, Token Code, etc) on a secondary screen, after the primary login information has been submitted.
Update Customer
Request:
{
"customerId": "38cf...cd9a",
"encryptionKey": "us1i...aqw=",
"name":"Person's New Name",
"userRef":"Person's New User Reference",
"defaultAccounts":[0,1],
"credentials": {
"institution": "bankslug",
"username": "98761234",
"password": "P455word"
}
}
<xml>
<customerId>38cf...cd9a</customerId>
<encryptionKey>us1i...aqw=</encryptionKey>
<name>My New Name</name>
<userRef>My New User Reference</userRef>
<defaultAccounts>
<defaultAccount>0</defaultAccount>
<defaultAccount>1</defaultAccount>
</defaultAccounts>
<credentials>
<institution>bankslug</institution>
<username>98761234</username>
<password>P455word</password>
</credentials>
</xml>
Response:
{
"success": "true",
"message": "Customer details have been updated",
"customer":{
"customerId":"8ab65f79-...-efcb2a33d4ef",
"encryptionKey":"4WooKrMT...XKdBPj1Etg="
}
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<success>true</success>
<message>Customer details have been updated</message>
<customer>
<customerId>067160f5-...-35451b6fddb0</customerId>
<encryptionKey>kWDzrn7...vUmd90A=</encryptionKey>
</customer>
</xml>
DESCRIPTION
Update the details associated with a customer in BankFeeds.
FUNCTION
Request Part | Value |
---|---|
Type | POST |
URL | /customer/update |
REQUEST HEADER
Name | Required | Value |
---|---|---|
X-API-KEY | Your API key (see API Keys) | |
Content-Type | The data format of your request (see Request Data Format) | |
Accept | The desired data format of the response (see Response Data Format) |
REQUEST BODY
Name | Required | Value |
---|---|---|
customerId | The unique customerId for the customer whose details you wish to update. | |
encryptionKey | The encryptionKey associated with the customerId that has previously been provided in a response from BankFeeds. | |
name | The updated name of the account holder. | |
userRef | The updated User Reference tag to be associated with the customer. This will only be used if the Users feature has been activated on your account. | |
defaultAccounts | The updated value for Defaults Accounts that indicate which customer accounts should be exported by default. The value(s) should be the account id for each account that you want to set as a default. | |
credentials | The updated credentials of the account holder. See the description of the credentials parameter of the Request Body of the Create Customer request. |
RETURN RESPONSE
The response will contain a success status of true
to confirm that the update has completed, along with a human friendly message. It will also contain the customerId
of the customer and the updated encryptionKey
.
Show Customer
Request:
{
"customerId": "38cf...cd9a",
"encryptionKey": "us1i...aqw="
}
<xml>
<customerId>38cf...cd9a</customerId>
<encryptionKey>us1i...aqw=</encryptionKey>
</xml>
Response:
{
"name": "A C Holder",
"institution": "bank_of_statements",
"customer": {
"customerId": "38cf...cd9a",
"encryptionKey": "r9ZZ...U0B4e6Tg="
}
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<name>A C Holder</name>
<institution>bank_of_statements</institution>
<customer>
<customerId>38cf...cd9a</customerId>
<encryptionKey>OqgUSVoNgC....Vowz1u7pKHU=</encryptionKey>
</customer>
</xml>
DESCRIPTION
Retrieve the name and the institution that is associated with a BankFeeds customer.
FUNCTION
Request Part | Value |
---|---|
Type | POST |
URL | /customer/get |
REQUEST HEADER
Name | Required | Value |
---|---|---|
X-API-KEY | Your API key (see API Keys) | |
Content-Type | The data format of your request (see Request Data Format) | |
Accept | The desired data format of the response (see Response Data Format) |
REQUEST BODY
Name | Required | Value |
---|---|---|
customerId | The unique customerId for the customer whose details you wish to retrieve. | |
encryptionKey | The encryptionKey associated with the customerId that has previously been provided in a response from BankFeeds. |
RETURN RESPONSE
The response will contain the name
and institution
associated with the supplied customerID
in BankFeeds. Additionally the response will contain the customerID
and encryptionKey
for this customer, which can then used in subsequent requests.
Delete Customer
Request:
{
"customerId": "38cf...cd9a",
"encryptionKey": "us1i...aqw="
}
<xml>
<customerId>38cf...cd9a</customerId>
<encryptionKey>us1i...aqw=</encryptionKey>
</xml>
Response:
{
"success": "true",
"message": "Customer has been removed",
"customerId": "453f...5bnt"
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<success>true</success>
<message>Customer has been removed</message>
<customerId>453f...5bnt</customerId>
</xml>
DESCRIPTION
If the encryptionKey
is provided as part of the request, this will purge a customer from BankFeeds. If the encryptionKey
is not provided then it will deactivate the user so that the user does not count towards the User Reference limit.
FUNCTION
Request Part | Value |
---|---|
Type | POST |
URL | /customer/delete |
REQUEST HEADER
Name | Required | Value |
---|---|---|
X-API-KEY | Your API key (see API Keys) | |
Content-Type | The data format of your request (see Request Data Format) | |
Accept | The desired data format of the response (see Response Data Format) |
REQUEST BODY
Name | Required | Value |
---|---|---|
customerId | The unique customerId for the customer whose details you wish to delete. | |
encryptionKey | The encryptionKey associated with the customerId that has previously been provided in a response from BankFeeds.When the encryptionKey is provded the user will be removed permanently. If the encryptionKey is not provided then it will deactivate the user so that the user does not count towards the User Reference limit. |
RETURN RESPONSE
The successful response will contain a success status of true
to confirm that the deletion has completed, per the given example. An error response will include the error code and reason for failure.
List Customer Accounts
Request:
{
"customerId":"07fd...adae1",
"encryptionKey":"YUn+...5Cmc="
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<customerId>07fd...dae1</customerId>
<encryptionKey>YUn+...Cmc=</encryptionKey>
</xml>
Example Accounts Response:
{
"accounts": [
{
"accountHolder": "Mary Jones",
"name": "Transaction Account",
"accountNumber": "456789",
"id": 0,
"bsb": "123-456",
"balance": "123.45",
"available": "123.45",
"accountType": "transaction"
},
{
"accountHolder": "Mary Jones and Tom Jones",
"name": "Savings Account",
"accountNumber": "945315",
"id": 1,
"bsb": "123-456",
"balance": "3123.45",
"available": "3123.45",
"interestRate": "3.89",
"accountType": "savings"
},
{
"accountHolder": "Mary Jones and Tom Jones",
"name": "Credit Card",
"accountNumber": "XXXX XXXX XXXX 7654",
"id": 2,
"bsb": "",
"balance": "-3193.45",
"available": "15553.55",
"interestRate": "13.99",
"accountType": "credit card"
}
],
"user_token": "4a7e30456efbdda658b15df03f38dcee",
"referral_code": "07fd...dae1",
"customer": {
"customerId": "07fd...dae1",
"encryptionKey": "qjha...uzw="
},
"dataRequestLink": "/v1/customer/data/eyJ0eX...YzE0hE_G_GReJrnzx4c"
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<accounts>
<account>
<accountHolder>Mary Jones</accountHolder>
<name>Transaction Account</name>
<accountNumber>456789</accountNumber>
<id>0</id>
<bsb>123-456</bsb>
<balance>123.45</balance>
<available>123.45</available>
<accountType>transaction</accountType>
</account>
<account>
<accountHolder>Mary Jones and Tom Jones</accountHolder>
<name>Savings Account</name>
<accountNumber>945315</accountNumber>
<id>1</id>
<bsb>123-456</bsb>
<balance>3123.45</balance>
<available>3123.45</available>
<interestRate>3.89</interestRate>
<accountType>savings</accountType>
</account>
<account>
<accountHolder>Mary Jones and Tom Jones</accountHolder>
<name>Credit Card</name>
<accountNumber>XXXX XXXX XXXX 7654</accountNumber>
<id>2</id>
<bsb/>
<balance>-3193.45</balance>
<available>15553.55</available>
<interestRate>13.99</interestRate>
<accountType>credit card</accountType>
</account>
</accounts>
<user_token>4a7e30456efbdda658b15df03f38dcee</user_token>
<referral_code>07fd...dae1</referral_code>
<customer>
<customerId>07fd...dae1</customerId>
<encryptionKey>qjha...uzw=</encryptionKey>
</customer>
<dataRequestLink>/v1/customer/data/eyJ0eX...YzE0hE_G_GReJrnzx4c</dataRequestLink>
</xml>
DESCRIPTION
Retrieve a list of the accounts that are available for the customer, including some basic information about the accounts.
FUNCTION
Request Part | Value |
---|---|
Type | POST |
URL | /customer/accounts |
REQUEST HEADER
Name | Required | Value |
---|---|---|
X-API-KEY | Your API key (see API Keys) | |
Content-Type | The data format of your request (see Request Data Format) | |
Accept | The desired data format of the response (see Response Data Format) |
REQUEST BODY
Name | Required | Value |
---|---|---|
customerId | The unique customerId for the customer whose data you wish to retrieve. | |
encryptionKey | The encryptionKey associated with the customerId that has previously been provided in a response from BankFeeds. |
RETURN RESPONSE
The response returned by the API depends on the customer for which the accounts are being retrieved.
If the customer’s credentials required an optional MFA credential (i.e. this would have been configured when creating the customer), then the response will be a Request for Additional Information. It will be necessary to provide the additional MFA information requested, and then the API will return a final response with the available accounts for the customer.
If the customer’s credentials do not require an optional MFA credential, then the response will contain the available accounts for this customer. See Example Accounts Response. The dataRequestLink
is a URL that should be used as the POST URL, along with the necessary Request Body elements, if you intend to make a subsequent request for the customer’s data. It has the benefit of assisting to maintain the session, meaning that it can allow you to make a subsequent data request without having to re-provide the MFA information. Note that the dataRequestLink
is a temporary URL that will expire after 15min. Any subsequent use will produce an error message.
A list of possible values for the accountType
can be found in Bank Account Types.
Retrieve Customer Data
Request for all available data:
{
"customerId":"07fd...dae1",
"encryptionKey":"YUn+VM4/xOg5o6mRLRNnwzEY2Typ7DMVh9M45HU5Cmc="
}
<xml>
<customerId>7d8b3441-d0ed-4da8-ac0d-30cbf0f2fedf</customerId>
<encryptionKey>WZtiORB1thB/P496Cwv6tOqtKNzabiiNcgMZoj3pq/o=</encryptionKey>
</xml>
Request with optional parameters:
{
"customerId":"07fd...dae1",
"encryptionKey":"YUn+VM4...5Cmc=",
"accounts":[0,1],
"generateRawFile": true,
"requestNumDays":30,
"async": true,
"callbackUrl": "http://example.com"
}
<xml>
<customerId>07fd...dae1</customerId>
<encryptionKey>YUn+VM4...5Cmc=</encryptionKey>
<accounts>0</accounts>
<accounts>1</accounts>
<generateRawFile>true</generateRawFile>
<requestNumDays>30</requestNumDays>
<async>true</async>
<callbackUrl>http://example.com</callbackUrl>
</xml>
Asynchronous Example Data Response:
{
"info": "Async Request",
"callbackUrl": "http://example.com"
}
<info>Async Request</info>
<callbackUrl>http://example.com</callbackUrl>
Asynchronous callbackUrl successfull submission response:
{
"dataVersion": 20170401,
"reference": "23bfc4fc-6719-4998-bde5-a16b9655f220",
"submissionTime": "2022-08-19T11:07:50",
"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": [],
"statementSummary": {},
"dayEndBalances": [],
"additionalDetails": {},
"statementAnalysis": [],
},
],
"userAddress": {}
},
"decisionMetrics": [],
"scoreModels": [],
"reportsLink": "/v1/reports/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJkMWJmMmYxOS1kZTY3LTQ1ZWMtYWJhNy1mZWVkYjAwM2IzNTgiLCJpc3MiOiJCYW5rRmVlZHMiLCJpYXQiOjE2NjA4NzMwNzMsImV4cCI6MTY2MDg3MzY3MywidXNlcl90b2tlbiI6IjlhMDIwZGRzazU0M3V2Z2xucnFtaGJqc3FyIiwiY3VzdG9tZXJJZCI6IjIzYmZjNGZjLTY3MTktNDk5OC1iZGU1LWExNmI5NjU1ZjIyMCIsIm5leHRTdGVwIjoicmVwb3J0cyJ9.Dsos68ZmfpXfZ9oNtxzoOqh8VKaRjNRXxkSPLHptrv8",
"customer": {
"customerId": "23bfc4fc-6719-4998-bde5-a16b9655f220",
"encryptionKey": "tmMK32fY4Fus2Qq4NADXTPfZD3mYqBwoaeHSti3JsiA=",
"userRef": "1234567"
}
}
Asynchronous callbackUrl error submission response:
{
"error": "The connection to your bank has expired. Please restart the process and try again. ",
"errorCode": 60006,
"reportsLink": "/v1/reports/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiI0YmIxZTc3Yi0yMTdhLTRhODItYjA0Ny03NmI3ZDkyODU4YTkiLCJpc3MiOiJCYW5rRmVlZHMiLCJpYXQiOjE2NjA4NzYxMDMsImV4cCI6MTY2MDg3NjcwMywidXNlcl90b2tlbiI6ImR0b2tvNWlrdmk1dHUzMmhqYzE0dGJ0OGNtIiwiY3VzdG9tZXJJZCI6IjIwZTFjMjdiLTEzMWItNDJkOC05YjBkLWE1NjgzMjE4N2E1NiIsIm5leHRTdGVwIjoicmVwb3J0cyJ9.VRuj2Lbr5ZFOmopdYcvwOu1_SD9oifvYevifuOcTNQg",
"customer": {
"customerId": "20e1c27b-131b-42d8-9b0d-a56832187a56",
"encryptionKey": "OgXwEK9FK+CMXVmp3wfKwuJmaTikF7GlldUQeCZ+vPk=",
"userRef": "1234567"
}
}
Synchronous Example Data Response:
{
"accounts": {
"boq": {
"accounts": [
{
"accountHolder": "Mr A C Holder",
"name": "Savings Account",
"accountNumber": "22035291",
"id": 0,
"bsb": "124-001",
"balance": "1.00",
"available": "1.00",
"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": "10-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 Statements",
"accountType": "savings"
}
]
}
},
"user_token": "cd7ef53597923fa13dbf4ffeddc97c7f",
"referral_code": "07fd...dae1",
"reportsLink": "/v1/reports/eyJ0eXA....VhfVC1tuDH9ypwXGg",
"customer": {
"customerId": "07fd...dae1",
"encryptionKey": "SGqr42...RXztU4I="
}
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<accounts>
<boq>
<accounts>
<account>
<accountHolder>Mr A C Holder</accountHolder>
<name>WebSavings</name>
<accountNumber>22114714</accountNumber>
<id>0</id>
<bsb>124-001</bsb>
<balance>2.27</balance>
<available>2.27</available>
<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>10-06-2015</endDate>
<minBalance>1.11</minBalance>
<maxBalance>3.27</maxBalance>
<dayEndBalances>
<dayEndBalance>
<date>2016-06-15</date>
<balance>2.27</balance>
</dayEndBalance>
</dayEndBalances>
<minDayEndBalance></minDayEndBalance>
<daysInNegative>0</daysInNegative>
<errorMessage></errorMessage>
<analysis/>
</statementData>
<institution>Bank of Statements</institution>
<accountType>savings</accountType>
</account>
</accounts>
</boq>
</accounts>
<user_token>1ebf619404f848bedad2d3e6b1288093</user_token>
<referral_code>07fd...dae1</referral_code>
<reportsLink>/v1/reports/eyJ0eXA....VhfVC1tuDH9ypwXGg</reportsLink>
<customer>
<customerId>07fd...dae1</customerId>
<encryptionKey>SGqr42...RXztU4I=</encryptionKey>
</customer>
</xml>
Synchronous 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",
"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",
"referral_code": "cda8...351f",
"reportsLink": "/v1/reports/eyJ0...29f0",
"customer": {
"customerId": "cda8...351f",
"encryptionKey": "Axpn...fGg="
}
}
<?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>
<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>
<referral_code>cda8...351f</referral_code>
<reportsLink>/v1/reports/eyJ0...29f0</reportsLink>
<customer>
<customerId>cda8...351f</customerId>
<encryptionKey>Axpn...fGg=</encryptionKey>
</customer>
</xml>
Synchronous Example Data Response, for version '20170401’:
{
"dataVersion": "20170401",
"reference": "TEST",
"submissionTime": "2017-05-08T17:44:00",
"bankData": {
"bankName": "Bank of Statements",
"bankSlug": "bank_of_statements",
"bankAccounts": [
{
"id": 0,
"accountType": "transaction",
"accountHolder": "Mary Jones",
"accountName": "Transaction Account",
"bsb": "123-456",
"accountNumber": "456789",
"currentBalance": "123.45",
"availableBalance": "123.45",
"transactions": [
{
"date": "2017-05-05",
"text": "Wage from delivery service job",
"amount": 409.73,
"type": "",
"balance": "371.24",
"tags": [
{
"thirdParty": "Wages"
},
{
"category": "Wages"
},
{
"creditDebit": "credit"
}
]
},
{
"date": "2017-05-05",
"text": "Wage from delivery service job",
"amount": 93.84,
"type": "",
"balance": "-38.49",
"tags": [
{
"thirdParty": "Wages"
},
{
"category": "Wages"
},
{
"creditDebit": "credit"
}
]
}
],
"statementSummary": {
"openingBalance": "-7474.80",
"totalCredits": "49541.44",
"totalDebits": "-41943.19",
"closingBalance": "123.45",
"minBalance": "-8430.71",
"minDayEndBalance": "-8133.41",
"daysInNegative": 88,
"searchPeriodStart": "2017-02-06",
"searchPeriodEnd": "2017-05-07",
"transactionsStartDate": "2017-02-06",
"transactionsEndDate": "2017-05-06"
},
"dayEndBalances": [
{
"date": "2017-05-07",
"balance": "123.45"
},
{
"date": "2017-05-06",
"balance": "123.45"
}
],
"additionalDetails": {
"interestRate": "",
"accountAddress": {
"text": "2 Smith St Sefton Park SA 5083 AUSTRALIA",
"streetLine": "2 Smith St",
"streetNumber": "2",
"streetName": "Smith",
"streetType": "Street",
"suburb": "Sefton Park",
"stateCode": "SA",
"state": "South Australia",
"postcode": "5083",
"countryCode": "au"
}
},
"statementAnalysis": [
{
"analysisCategory": {
"name": "Wages",
"analysisPoints": [
{
"name": "startDate",
"value": "2017-02-07",
"title": "Start Date",
"type": "date"
},
{
"name": "endDate",
"value": "2017-05-05",
"title": "End Date",
"type": "date"
},
{
"name": "totalAmount",
"value": 4563.3,
"title": "Total Amount",
"type": "money"
},
{
"name": "countOfTransactions",
"value": 18,
"title": "Count of Transactions",
"type": "integer"
},
{
"name": "totalAmountLast30Days",
"value": 1155.97,
"title": "Total Amount - Last 30 Days",
"type": "money"
},
{
"name": "monthlyAmountAverage",
"value": 1480.99,
"title": "Monthly Average Amount",
"type": "money"
},
{
"name": "averageTransactionAmount",
"value": 253.52,
"title": "Average Transaction Amount",
"type": "money"
},
{
"name": "daysSinceLastTransaction",
"value": 3,
"title": "Days Since Last Transaction",
"type": "integer"
},
{
"name": "totalAmountCredits",
"value": 4563.3,
"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": "2017-02-07",
"title": "Start Date",
"type": "date"
},
{
"name": "endDate",
"value": "2017-05-05",
"title": "End Date",
"type": "date"
},
{
"name": "totalAmount",
"value": 4563.3,
"title": "Total Amount",
"type": "money"
},
{
"name": "frequency",
"value": 6,
"title": "Frequency",
"type": "integer"
},
{
"name": "frequencyDay",
"value": "Fri",
"title": "Frequency Day",
"type": "string"
},
{
"name": "countOfTransactions",
"value": 18,
"title": "Count of Transactions",
"type": "integer"
},
{
"name": "totalAmountLast30Days",
"value": 1155.97,
"title": "Total Amount - Last 30 Days",
"type": "money"
},
{
"name": "monthlyAmountAverage",
"value": 1480.99,
"title": "Monthly Average Amount",
"type": "money"
},
{
"name": "averageTransactionAmount",
"value": 253.52,
"title": "Average Transaction Amount",
"type": "money"
},
{
"name": "daysSinceLastTransaction",
"value": 3,
"title": "Days Since Last Transaction",
"type": "integer"
},
{
"name": "totalAmountCredits",
"value": 4563.3,
"title": "Total Amount - Credits",
"type": "money"
},
{
"name": "totalAmountDebits",
"value": 0,
"title": "Total Amount - Debits",
"type": "money"
}
],
"transactions": [
{
"date": "2017-05-05",
"text": "Wage from delivery service job",
"amount": 409.73,
"type": "",
"balance": "371.24",
"tags": [
{
"thirdParty": "Wages"
},
{
"category": "Wages"
},
{
"creditDebit": "credit"
}
]
},
{
"date": "2017-05-05",
"text": "Wage from delivery service job",
"amount": 93.84,
"type": "",
"balance": "-38.49",
"tags": [
{
"thirdParty": "Wages"
},
{
"category": "Wages"
},
{
"creditDebit": "credit"
}
]
}
]
}
]
}
}
]
}
],
"userAddress": {
"text": "2 Smith St Sefton Park SA 5083 AUSTRALIA",
"streetLine": "2 Smith St",
"streetNumber": "2",
"streetName": "Smith",
"streetType": "Street",
"suburb": "Sefton Park",
"stateCode": "SA",
"state": "South Australia",
"postcode": "5083",
"countryCode": "au"
}
},
"decisionMetrics": [
{
"id": "DM001",
"name": "Wages - Monthly",
"descriptor": "",
"type": "money",
"value": "6469.24"
},
{
"id": "DM002",
"name": "Centrelink - Monthly",
"descriptor": "",
"type": "money",
"value": "5891.46"
},
{
"id": "DM003",
"name": "Centrelink as a Percentage of Total Income",
"descriptor": "",
"type": "percentage",
"value": "47.66"
},
{
"id": "DM004",
"name": "Number of Dishonours",
"descriptor": "",
"type": "integer",
"value": 134
},
{
"id": "DM005",
"name": "Number of SACC Dishonours",
"descriptor": "",
"type": "integer",
"value": 70
},
{
"id": "DM006",
"name": "Percentage of Income Spent on Day of Deposit ",
"descriptor": "",
"type": "percentage",
"value": "346.60"
},
{
"id": "DM007",
"name": "Gambling - Monthly",
"descriptor": "",
"type": "money",
"value": "2617.56"
},
{
"id": "DM008",
"name": "Expected Pay Date for Largest Income Source",
"descriptor": "",
"type": "string",
"value": "Past (29-04-2017)"
},
{
"id": "DM009",
"name": "SACC Loans Funded - Statement Period",
"descriptor": "",
"type": "money",
"value": "21418.45"
},
{
"id": "DM010",
"name": "SACC Loan Repayments - Last 30 Days",
"descriptor": "",
"type": "money",
"value": "6170.98"
},
{
"id": "DM011",
"name": "SACC Repayments for Ongoing Loans - Predicted Next 30 Days",
"descriptor": "",
"type": "money",
"value": "839.83"
},
{
"id": "DM012",
"name": "Number of SACC Providers",
"descriptor": "",
"type": "integer",
"value": 4
},
{
"id": "DM013",
"name": "Living Expenses - Monthly ",
"descriptor": "",
"type": "money",
"value": "14899.00"
},
{
"id": "DM014",
"name": "Collection and Consolidation - Monthly",
"descriptor": "",
"type": "money",
"value": "3945.78"
},
{
"id": "DM015",
"name": "Credit Card Repayments - Monthly",
"descriptor": "",
"type": "money",
"value": "2034.00"
},
{
"id": "DM016",
"name": "Other Credits - Monthly",
"descriptor": "",
"type": "money",
"value": "16646.18"
}
],
"user_token": "ggq3hmaahb7nlrff8iahpc5hb0"
}
<?xml version="1.0" encoding="utf-8"?>
<provisoReport dataVersion="20170401">
<reference>TEST</reference>
<submissionTime>2017-05-08T16:58: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>
<accountName>Transaction Account</accountName>
<bsb>123-456</bsb>
<accountNumber>456789</accountNumber>
<currentBalance>123.45</currentBalance>
<availableBalance>123.45</availableBalance>
<transactions>
<transaction>
<date>2017-05-05</date>
<description>Wage from delivery service job</description>
<amount>409.73</amount>
<balance>371.24</balance>
<type/>
<tags>
<tag name="thirdParty">Wages</tag>
<tag name="category">Wages</tag>
<tag name="creditDebit">credit</tag>
</tags>
</transaction>
<transaction>
<date>2017-05-05</date>
<description>Wage from delivery service job</description>
<amount>93.84</amount>
<balance>-38.49</balance>
<type/>
<tags>
<tag name="thirdParty">Wages</tag>
<tag name="category">Wages</tag>
<tag name="creditDebit">credit</tag>
</tags>
</transaction>
</transactions>
<statementSummary>
<openingBalance>-7474.80</openingBalance>
<totalCredits>49541.44</totalCredits>
<totalDebits>-41943.19</totalDebits>
<closingBalance>123.45</closingBalance>
<minBalance>-8430.71</minBalance>
<minDayEndBalance>-8133.41</minDayEndBalance>
<daysInNegative>88</daysInNegative>
<searchPeriodStart>2017-02-06</searchPeriodStart>
<searchPeriodEnd>2017-05-07</searchPeriodEnd>
<transactionsStartDate>2017-02-06</transactionsStartDate>
<transactionsEndDate>2017-05-06</transactionsEndDate>
<dayEndBalances>
<dayEndBalance>
<date>2017-05-07</date>
<balance>123.45</balance>
</dayEndBalance>
<dayEndBalance>
<date>2017-05-06</date>
<balance>123.45</balance>
</dayEndBalance>
</dayEndBalances>
<statementAnalysis>
<analysisCategory name="Wages">
<analysisPoints>
<analysisPoint dataType="date" name="startDate" title="Start Date">2017-02-06</analysisPoint>
<analysisPoint dataType="date" name="endDate" title="End Date">2017-05-06</analysisPoint>
<analysisPoint dataType="money" name="totalAmount" title="Total Amount">7588.04</analysisPoint>
<analysisPoint dataType="integer" name="countOfTransactions" title="Count of Transactions">24</analysisPoint>
<analysisPoint dataType="money" name="totalAmountLast30Days" title="Total Amount - Last 30 Days">2499.63</analysisPoint>
<analysisPoint dataType="money" name="monthlyAmountAverage" title="Monthly Average Amount">2429.88</analysisPoint>
<analysisPoint dataType="money" name="averageTransactionAmount" title="Average Transaction Amount">316.17</analysisPoint>
<analysisPoint dataType="integer" name="daysSinceLastTransaction" title="Days Since Last Transaction">2</analysisPoint>
<analysisPoint dataType="money" name="totalAmountCredits" title="Total Amount - Credits">7588.04</analysisPoint>
<analysisPoint dataType="money" name="totalAmountDebits" title="Total Amount - Debits">0</analysisPoint>
<analysisPoint dataType="integer" name="countOfProviders" title="Count of Providers">1</analysisPoint>
</analysisPoints>
<transactionGroups>
<transactionGroup name="Wage from delivery service job">
<analysisPoints>
<analysisPoint dataType="date" name="startDate" title="Start Date">2017-02-06</analysisPoint>
<analysisPoint dataType="date" name="endDate" title="End Date">2017-05-06</analysisPoint>
<analysisPoint dataType="money" name="totalAmount" title="Total Amount">7588.04</analysisPoint>
<analysisPoint dataType="integer" name="frequency" title="Frequency">4</analysisPoint>
<analysisPoint dataType="string" name="frequencyDay" title="Frequency Day">Fri</analysisPoint>
<analysisPoint dataType="integer" name="countOfTransactions" title="Count of Transactions">24</analysisPoint>
<analysisPoint dataType="money" name="totalAmountLast30Days" title="Total Amount - Last 30 Days">2499.63</analysisPoint>
<analysisPoint dataType="money" name="monthlyAmountAverage" title="Monthly Average Amount">2429.88</analysisPoint>
<analysisPoint dataType="money" name="averageTransactionAmount" title="Average Transaction Amount">316.17</analysisPoint>
<analysisPoint dataType="integer" name="daysSinceLastTransaction" title="Days Since Last Transaction">2</analysisPoint>
<analysisPoint dataType="money" name="totalAmountCredits" title="Total Amount - Credits">7588.04</analysisPoint>
<analysisPoint dataType="money" name="totalAmountDebits" title="Total Amount - Debits">0</analysisPoint>
</analysisPoints>
<transactions>
<transaction>
<date>2017-05-05</date>
<description>Wage from delivery service job</description>
<amount>409.73</amount>
<balance>371.24</balance>
<type/>
<tags>
<tag name="thirdParty">Wages</tag>
<tag name="category">Wages</tag>
<tag name="creditDebit">credit</tag>
</tags>
</transaction>
<transaction>
<date>2017-05-05</date>
<description>Wage from delivery service job</description>
<amount>93.84</amount>
<balance>-38.49</balance>
<type/>
<tags>
<tag name="thirdParty">Wages</tag>
<tag name="category">Wages</tag>
<tag name="creditDebit">credit</tag>
</tags>
</transaction>
</transactions>
</transactionGroup>
</transactionGroups>
</analysisCategory>
</statementAnalysis>
</statementSummary>
<additionalDetails>
<interestRate/>
<address>
<text>2 Smith St Sefton Park SA 5083 AUSTRALIA</text>
<streetLine>2 Smith St</streetLine>
<levelNumber/>
<levelType/>
<buildingName/>
<unitNumber/>
<unitType/>
<streetNumber>2</streetNumber>
<streetName>Smith</streetName>
<streetType>Street</streetType>
<streetSuffix/>
<suburb>Sefton Park</suburb>
<state>South Australia</state>
<stateCode>SA</stateCode>
<postcode>5083</postcode>
<country/>
<countryCode>au</countryCode>
</address>
</additionalDetails>
</bankAccount>
</bankAccounts>
<address>
<text>2 Smith St Sefton Park SA 5083 AUSTRALIA</text>
<streetLine>2 Smith St</streetLine>
<levelNumber/>
<levelType/>
<buildingName/>
<unitNumber/>
<unitType/>
<streetNumber>2</streetNumber>
<streetName>Smith</streetName>
<streetType>Street</streetType>
<streetSuffix/>
<suburb>Sefton Park</suburb>
<state>South Australia</state>
<stateCode>SA</stateCode>
<postcode>5083</postcode>
<country/>
<countryCode>au</countryCode>
</address>
</bankData>
<decisionMetrics>
<decisionMetric descriptor="" id="DM001" name="Wages - Monthly" type="money">6808.55</decisionMetric>
<decisionMetric descriptor="" id="DM002" name="Centrelink - Monthly" type="money">6330.44</decisionMetric>
<decisionMetric descriptor="" id="DM003" name="Centrelink as a Percentage of Total Income" type="percentage">48.18</decisionMetric>
<decisionMetric descriptor="" id="DM004" name="Number of Dishonours" type="integer">143</decisionMetric>
<decisionMetric descriptor="" id="DM005" name="Number of SACC Dishonours" type="integer">67</decisionMetric>
<decisionMetric descriptor="" id="DM006" name="Percentage of Income Spent on Day of Deposit " type="percentage">331.64</decisionMetric>
<decisionMetric descriptor="" id="DM007" name="Gambling - Monthly" type="money">1561.13</decisionMetric>
<decisionMetric descriptor="" id="DM008" name="Expected Pay Date for Largest Income Source" type="date">2017-05-10</decisionMetric>
<decisionMetric descriptor="" id="DM009" name="SACC Loans Funded - Statement Period" type="money">18152.03</decisionMetric>
<decisionMetric descriptor="" id="DM010" name="SACC Loan Repayments - Last 30 Days" type="money">9119.02</decisionMetric>
<decisionMetric descriptor="" id="DM011" name="SACC Repayments for Ongoing Loans - Predicted Next 30 Days" type="money">1256.91</decisionMetric>
<decisionMetric descriptor="" id="DM012" name="Number of SACC Providers" type="integer">4</decisionMetric>
<decisionMetric descriptor="" id="DM013" name="Living Expenses - Monthly " type="money">16410.21</decisionMetric>
<decisionMetric descriptor="" id="DM014" name="Collection and Consolidation - Monthly" type="money">4076.32</decisionMetric>
<decisionMetric descriptor="" id="DM015" name="Credit Card Repayments - Monthly" type="money">2231.73</decisionMetric>
<decisionMetric descriptor="" id="DM016" name="Other Credits - Monthly" type="money">18508.29</decisionMetric>
</decisionMetrics>
<user_token>ggq3hmaahb7nlrff8iahpc5hb0</user_token>
</provisoReport>
DESCRIPTION
Retrieve the statement data from a customer’s accounts. It will include all transactions (for the date range specified for your account) as well as some summary and analysis data.
FUNCTION
Request Part | Value |
---|---|
Type | POST |
URL | /customer/data |
Existing Session URL | /customer/data/xxx |
The Existing Session URL refers to the temporary dataRequestLink
URL that can be returned via API requests such as
List Customer Accounts. This URL contains a session attribute that will allow you to retrieve
account data by using the existing session. These URLs expire after 15min to ensure that there is an active session.
Any subsequent use will produce an error message.
REQUEST HEADER
Name | Required | Value |
---|---|---|
X-API-KEY | Your API key (see API Keys) | |
Content-Type | The data format of your request (see Request Data Format) | |
Accept | The desired data format of the response (see Response Data Format) | |
X-OUTPUT-VERSION | The desired version of this API function to implement (see API Versions) Supported values:
|
REQUEST BODY
Name | Required | Value |
---|---|---|
customerId | The unique customerId for the customer whose data you wish to retrieve. | |
encryptionKey | The encryptionKey associated with the customerId that has previously been provided in a response from BankFeeds. | |
async | Default is false . If set to true this will trigger the asynchronous export method which will deliver the submission to accompanied callbackUrl asynchronously. If callbackUrl is not specified, the callback URL configured within the account settings will be used. If there is error during submission, an error message will be delivered to the callbackUrl instead. | |
callbackUrl | This is required if async parameter is set to true and callback URL is not configured within the account settings. This is the endpoint where the submissions is delivered asynchronously. | |
accounts | The account number * of each account from which you want to retrieve information. If omitted, then data for the Default Accounts (that were configured for this customer) will be retrieved. If no Default Accounts have been configured for the customer then all accounts will be retrieved.* Instead of account number, `id` (from accounts list) can be supplied. However, those `id`s are not guaranteed to be stable. | |
requestNumDays | The number of days prior to the current date for which you want to restrict the data returned. It provides the ability to retrieve transaction data from a specified number of days prior to the current date, up until the current date. Accepts a numeric value up to and including a maximum of 365. | |
generateRawFile | Default is false . If set to true then a file containing the raw bank data will also be supplied with the files downloaded through the reportsLink URL. 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: At this time V1 raw data formats are unavailable. |
RETURN RESPONSE
The response returned by the API depends on the customer for which the accounts are being retrieved.
If the customer’s credentials required an optional MFA credential (i.e. this would have been configured when creating the customer), then the response will be a Request for Additional Information. It will be necessary to provide the additional MFA information requested, and then the API will return a final response with the requested account data for the customer.
If the customer’s credentials do not require an optional MFA credential, then the response will contain the requested account data for the customer. See Example Data Response. The reportsLink
is a URL that should be used as the GET URL if you intend to make a subsequent request for the customer’s report file. It has the benefit of assisting to maintain the session, meaning that it can allow you to make a subsequent report request without having to re-provide the MFA information. Note that the reportsLink
is a temporary URL that will expire after 10min. Any subsequent use will produce an error message.
A list of possible values for the accountType
can be found in Bank Account Types.
Retrieve Customer Reports
DESCRIPTION
Retrieve any files that were loaded or generated via the BankStatements service as part of the BankFeeds API requests.
BankFeeds API responses that include customer transaction data (such as the Data Request) will also include a reportsLink
, which is the URL to use in order to retrieve the related “report” files.
Note that the reportsLink
is a temporary URL that will expire after 10min. Any subsequent use will produce an error message.
FUNCTION
Request Part | Value |
---|---|
Type | GET |
URL | /reports/xxx |
REQUEST HEADER
Name | Required | Value |
---|---|---|
X-API-KEY | Your API key (see API Keys) | |
Accept | The desired data format of the response (see Response Data Format) |
RETURN RESPONSE
If successful, the response will be a ZIP file containing a set of reports.
If there was an error, then the response will be an error message in the Response Data Format that was specified by the request. It is therefore important to specify the Response Data Format in order to retrieve any potential error responses in the format you require (i.e. even though a successful response will be a ZIP).
Users
If your account has been configured to enable Users functionality, it will be possible for you to associate a tag with the customer entities that you create via the API. These tags are essentially a label that you can use to associate multiple BankFeeds customer credentials with a single real-life customer/user. For example, a single real-life user/customer may bank with multiple banking institutions, requiring you to generate multiple BankFeeds customer credentials via the API.
BankFeeds allows up to 10 customer credentials to be associated with the same User Reference.
Additionally, if your account has been configured to enable Users functionality, you will have access to API functions that enable functionality such as listing all customer credentials associated with a User Reference.
MODIFIED RETURN RESPONSES
Example of the response data defining a customer when a User Reference was set
{
"customerId":"56f0...7164",
"encryptionKey":"ewP7...U9SY=",
"userRef":"my-user-ref"
}
<xml>
<customerId>56f0...7164</customerId>
<encryptionKey>ewP7...U9SY=</encryptionKey>
<userRef>my-user-ref</userRef>
</xml>
Example of the response data defining a customer (when returned as part of a larger response) when a User Reference was set
{
...
"customer": {
"customerId": "9cef74e0-...-0768c9d576dc",
"encryptionKey": "ypMlFa2...BOXjcc7ONQ\\/k=",
"userRef":"my-user-ref"
}
...
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
...
<customer>
<customerId>9cef74e0-....-0768c9d576dc</customerId>
<encryptionKey>OqgUSVoNgC....Vowz1u7pKHU=</encryptionKey>
<userRef>my-user-ref</userRef>
</customer>
...
</xml>
The User Reference will be automatically included in relevant API responses when retrieving data for a customer that was previously configured with a User Reference tag.
List Customer Users
Example Data Response:
{
"customers": [
"6bef9c33-bb03-4bf5-9e86-41de23865dcd",
"ba5324ce-ee52-4c6c-b9c8-028aec91e813"
]
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<customers>
<customers>6bef9c33-bb03-4bf5-9e86-41de23865dcd</customers>
<customers>ba5324ce-ee52-4c6c-b9c8-028aec91e813</customers>
</customers>
</xml>
DESCRIPTION
Retrieve a list of customerId
values associated with the supplied User Reference.
FUNCTION
Request Part | Value |
---|---|
Type | GET |
URL | /user/xxx |
REQUEST HEADER
Name | Required | Value |
---|---|---|
X-API-KEY | Your API key (see API Keys) | |
Content-Type | The data format of your request (see Request Data Format) | |
Accept | The desired data format of the response (see Response Data Format) |
RETURN RESPONSE
A successful response will contain a list of all the customerId
values associated with the supplied User Reference.
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.
BankFeeds deals with these situations by returning a response containing a Request for Additional Information. This information will generally need to be provided by the end user themselves, so for these users, an automatic feed of data that can be refreshed at will, is not possible.
Request for Additional Information
Response containing a ‘Request for Additional Information’:
{
"type": "additionalInformationNeeded",
"title": "NetCode token required",
"fields": [
{
"type": "header",
"text": "Please Enter Your NetCode"
},
{
"type": "instructions",
"text": "How to use your security Token"
},
{
"type": "set",
"text": "",
"subElements": [
{
"type": "instructions",
"text": "1. Press the button on your token"
},
{
"type": "instructions",
"text": "2. A unique NetCode will be displayed on the token's screen"
},
{
"type": "instructions",
"text": "3. Enter your 6 digit NetCode below"
}
]
},
{
"type": "input",
"fieldID": "netcode",
"text": ""
}
],
"submitTo": "\\/v1\\/followupRequest\\/eyJ0eXAiOiJKV1MiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJCYW5rRmVlZHMiLCJpYXQiOjE0MzkzNDM3NjUsImV4cCI6MTQzOTM0NDM2NSwidXNlcl90b2tlbiI6IjQ0YmUyNmFhYTc2Y2IyOWRiNzU2ZTYwMDAwMWI1ZmY5IiwicmVxdWlyZWRGaWVsZHMiOlsibmV0Y29kZSJdLCJjdXN0b21lcklkIjoiMGYyYTdlZWItYmI3Ny00MDYzLTllNDItY2RkNjRjYTFhZGJkIiwibmV4dFN0ZXAiOiJtZmEifQ.60iVrCMaH928ytPi9VNtdR8VmvWHqTV67JMzvyGIp74",
"expiresIn": 600,
"customer": {
"customerId": "0f2a7eeb-...-cdd64ca1adbd",
"encryptionKey": "FP6c61...fjqyhafGs3QVQIY="
}
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<type>additionalInformationNeeded</type>
<title>NetCode token required</title>
<fields>
<field>
<type>header</type>
<text>Please Enter Your NetCode (123456)</text>
</field>
<field>
<type>instructions</type>
<text>How to use your security Token</text>
</field>
<field>
<type>set</type>
<text></text>
<subElements>
<subElement>
<type>instructions</type>
<text>1. Press the button on your token</text>
</subElement>
<subElement>
<type>instructions</type>
<text>2. A unique NetCode will be displayed on the token's screen</text>
</subElement>
<subElement>
<type>instructions</type>
<text>3. Enter your 6 digit NetCode below</text>
</subElement>
</subElements>
</field>
<field>
<type>input</type>
<fieldID>netcode</fieldID>
<text></text>
</field>
</fields>
<submitTo>/v1/followupRequest/eyJ0eXAiOiJKV1MiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJCYW5rRmVlZHMiLCJpYXQiOjE0MzkzNDcwMTYsImV4cCI6MTQzOTM0NzYxNiwidXNlcl90b2tlbiI6IjgwYTRhMWI3MWM1YjY5MDk1YTE0MjlmYThiMjBkMWZlIiwicmVxdWlyZWRGaWVsZHMiOlsibmV0Y29kZSJdLCJjdXN0b21lcklkIjoiM2RjZDYyMDctNmZhNC00NjYyLTg0ODUtYTFhZTgzYWM2YTAxIiwibmV4dFN0ZXAiOiJtZmEifQ.PX_5ueTQtN0BkmdruUPHMJ7nPD9cVWcU7C2SfFaTnQ0</submitTo>
<expiresIn>600</expiresIn>
<customer>
<customerId>3dcd6207-...-a1ae83ac6a01</customerId>
<encryptionKey>MocXzM...TSK8FMwb3Gr28+1Q=</encryptionKey>
</customer>
</xml>
When you submit a request to create, load accounts from, or load transaction data from a customer who requires MFA or CAPTCHA, the API will return a response that contains a Request for Additional Information. A response of this type can be identified by the presence of a type
element with the value additionalInformationNeeded
.
See the example Response containing a 'Request for Additional Information’.
The request for additional information will describe all the data needed in the Followup Request in order to verify customer access and finalise the original data request.
While each bank/institution require different MFA information (as described via the fields
), the general format of the request for additional information will be the same each time.
Element | Description |
---|---|
type | This will have a value of additionalInformationNeeded and can be used to determine if the response received by the BankFeeds API is a request for additional information. |
title | A human friendly description of the information required. |
fields | An array of field elements that can include textual instructions, images, headings, input fields, buttons, etc, which instruct the user on what is required, and how to proceed. See the list of field types. |
submitTo | This is the domain relative URL where the followup request should be submitted. The long string of characters after /followupRequest/ is a json web token, that contains additional information that must be persisted for the following request. It cannot be modified, and any modification to the token will trigger an error. |
expiresIn | The expiration time for the submission URL (i.e. the submitTo ). It is the time in seconds until the submission URL will be considered expired and can no longer be used. |
customer | The current information about the customer will be provided. Attributes
|
Reusable MFA
Reusable MFA Example - Request that indicates the data can be stored for subsequent use
{
"type": "additionalInformationNeeded",
"title": "Please Select Your Profile",
"fields": [
{
"type": "instructions",
"text": "Your Westpac account has multiple profiles available. Please select which profile you would like to submit data for."
},
{
"type": "options",
"text": "",
"fieldID": "profile",
"values": {
"0123": "Acme Pty Ltd - Business banking",
"4567": "Bob Green - Personal banking"
}
},
{
"fieldID": "reusableMfaId",
"type": "hidden",
"text": "",
"values": "westpacProfileSelection",
"htmlAttrs": ""
}
],
"submitTo": "/v1/followupRequest/eyJ0e...cA",
"expiresIn": null,
"customer": {
"customerId": "10f...410",
"encryptionKey": "d3O...IJQ"
}
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<type>additionalInformationNeeded</type>
<title>Please Select Your Profile</title>
<fields>
<field>
<type>instructions</type>
<text>Your Westpac account has multiple profiles available. Please select which profile you would like to submit data for.</text>
</field>
<field>
<type>options</type>
<text/>
<fieldID>profile</fieldID>
<values>
<value>Acme Pty Ltd - Business banking</value>
<value>Bob Green - Personal banking</value>
</values>
</field>
<field>
<fieldID>reusableMfaId</fieldID>
<type>hidden</type>
<text/>
<values>westpacProfileSelection</values>
<htmlAttrs/>
</field>
</fields>
<submitTo>/v1/followupRequest/eyJ0e...cA</submitTo>
<expiresIn/>
<customer>
<customerId>10f...410</customerId>
<encryptionKey>d3O...IJQ</encryptionKey>
</customer>
</xml>
In some scenarios, the Request for Additional Information that you receive will not be for authentication purposes, but instead simply be a prompt to submit additional input for the customer.
The data requested in this scenario is expected to be the same each time that the customer’s accounts are accessed. This allows us to potentially store the customer’s response for all subsequent interactions with their account, in order to avoid requesting the information from the customer each time an interaction with the API occurs.
We refer to this request for additional non-authentication information reusable MFA. This is to indicate that unlike most traditional MFA responses that are a one-time only use, this response can be stored and reused for future requests.
An example scenario is a prompt for the customer to select their profile after successfully logging into their online banking system.
You can identify these types of MFA requests by the presence of the reusableMfaId
field (see the 'Request that indicates the data can be stored for subsequent use’ example). The value of this field will be a unique name for this specific MFA Request.
In order to indicate to the BankFeeds API service to store the submitted data in the Followup Request, you must add the reusableMfaId
field with the related value. BankFeeds API will store the response encrypted with the customer credential data so that BankFeeds API can handle this step automatically for all subsequent interactions with the API for the customer.
Followup Request
Followup Request (send to the 'submitTo’ url, at BankFeeds)
{
"customerId": "9914f40d-...-ab1391fadd4f",
"encryptionKey": "KMHwEd...C+DV414iDlM\\/\\/Vg=",
"netcode": "123456"
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<customerId>9fb16368-...-f81c229d39a1</customerId>
<encryptionKey>PrfWOk...O5ST3OFiIq1ykXuk=</encryptionKey>
<netcode>123456</netcode>
</xml>
DESCRIPTION
Provide the additional information that a customer’s financial institution has requested. This Request for Additional Information is typically as a result of the customer’s institution requiring MFA in order to provide access to the customer’s data.
FUNCTION
Request Part | Value |
---|---|
Type | POST |
URL | /followupRequest/xxx |
The URL must be the temporary submitTo
URL that was included in the Request for Additional Information. This URL contains information to be able to provide the originally requested data after the MFA process has completed. The URL can not be used after the session or URL itself has expired.
REQUEST HEADER
Name | Required | Value |
---|---|---|
X-API-KEY | Your API key (see API Keys) | |
Content-Type | The data format of your request (see Request Data Format) | |
Accept | The desired data format of the response (see Response Data Format) |
REQUEST BODY
Name | Required | Value |
---|---|---|
customerId | The unique customerId for the customer whose details you wish to update. | |
encryptionKey | The encryptionKey associated with the customerId that has previously been provided in a response from BankFeeds. | |
field(s) | The follow up request must include the customerId and encryptionKey, along with a value for each field which has a .
The request must contain all the individual field elements that were sent in the request for additional information, that have a non-blank fieldId attribute. The fieldId will be the key that must be submitted as part of this request, and the value will be the correct answer.
This ensures that all the information that was requested can be returned as part of the followup. Note that the number of field elements returned by the API is subject to change by each institution, and so your application should not hard-code any assumptions about the number of fields being returned based on what is currently returned by the API. |
RETURN RESPONSE
If successful, the API will return the data that was originally requested (refer to the documentation for that specific API function for examples).
If unsuccessful, the API may respond with another Request for Additional Information to provide another opportunity to submit the required information, or potentially with an error message.
The callback response may contain an additional field storedReusableMfa
which if present will have the value true
. The presence of this field and value indicate that BankFeeds API has stored the reusable MFA data (i.e. a static value not used for authentication) with the customer’s credentials, thereby simplifying future interactions with the API for this customer. This will only occur if the reusableMfaId
field and associated value were provided as part of the Followup Request.
Field Types
Input Field
{
"type": "input",
"fieldID": "netcode",
"text": ""
}
<field>
<type>input</type>
<fieldID>netcode</fieldID>
<text></text>
</field>
Password Field
{
"type": "password",
"fieldID": "password",
"text": ""
}
<field>
<type>input</type>
<fieldID>netcode</fieldID>
<text></text>
</field>
Header Field
{
"type": "header",
"text": "Please Enter Your NetCode"
}
<field>
<type>header</type>
<text>Please Enter Your NetCode</text>
</field>
Instruction Field
{
"type": "instructions",
"text": "How to use your security Token"
}
<field>
<type>instructions</type>
<text>How to use your security Token</text>
</field>
Image Field
{
"type": "image",
"text": "",
"src": "data:image\\/gif;base64,R0lGODdhJAAkAPcAAAwWLHSQrI...AAhqwCtyhyUzAcRzCBA0nC6EIR7x2wAoWJCAAOw==",
"width": 36,
"height": 36,
"alt": ""
}
<field>
<type>image</type>
<text></text>
<src>data:image/gif;base64,R0lGODdhJAAkAPcAAOQWBIyOnMTK3Nzq5Pzm1...MeoimPOMSBCFQIPBKzQP0YZCQL4YpAAgIAOw==</src>
<width>36</width>
<height>36</height>
<alt></alt>
</field>
Captcha Field
{
"type": "captcha",
"text": "",
"fieldID": "captcha",
"src": "data:image\\/gif;base64,R0lGODlhLAE8AP...pbn2xr38pnRehrnWx1wqY49uEXnCQgAOw==",
"width": 300,
"height": 60,
"alt": ""
}
<field>
<type>captcha</type>
<text></text>
<fieldID>captcha</fieldID>
<src>data:image/gif;base64,R0lGODlhLAE8AP...pbn2xr38pnRehrnWx1wqY49uEXnCQgAOw==</src>
<width>300</width>
<height>60</height>
<alt></alt>
</field>
Hidden Field
{
"type": "hidden",
"text": "",
"fieldID": "seq"
}
<field>
<type>hidden</type>
<text></text>
<fieldID>seq</fieldID>
</field>
Options Field
{
"type": "options",
"text": "",
"fieldID": "opt",
"values":{
"value1":"Display Value 1",
"value2":"Display Value 2"
}
}
<field>
<type>options</type>
<text></text>
<fieldID>opt</fieldID>
<values>
</values>
</field>
Html Field
{
"type": "html",
"text": "<p id=\"selectionCounter\" style=\"font-weight: bold;\"> <b>0 \\/ 3 selected<\\/b> <\\/p>"
}
<field>
<type>html</type>
<text><p id="selectionCounter" style="font-weight: bold;"> <b>0 / 3 selected</b> </p></text>
</field>
Field Set
{
"type": "set",
"text": "",
"subElements": [
{
"type": "instructions",
"text": "1. Press the button on your token"
},
{
"type": "instructions",
"text": "2. A unique NetCode will be displayed on the token's screen"
},
{
"type": "instructions",
"text": "3. Enter your 6 digit NetCode below"
}
]
}
<field>
<type>set</type>
<text></text>
<subElements>
<subElement>
<type>instructions</type>
<text>1. Press the button on your token</text>
</subElement>
<subElement>
<type>instructions</type>
<text>2. A unique NetCode will be displayed on the token's screen</text>
</subElement>
<subElement>
<type>instructions</type>
<text>3. Enter your 6 digit NetCode below</text>
</subElement>
</subElements>
</field>
Javascript
{
"type": "javascript",
"text": "var pad = \"DB4E98A2FF880701CB\"; function selectCell(column, row) { var index = (3 * row) + column; var seqCode = document.getElementById('seq'); }"
}
<field>
<type>javascript</type>
<text>var pad = "B3C5E91337DAEB774B"; function selectCell(column, row) { var index = (3 * row) + column; var seqCode = document.getElementById('seq'); }</text>
</field>
Button
{
"type": "button",
"text": "",
"htmlAttrs": {
"value": "Clear",
"onclick": "resetSeqCode()",
"class": "mainButton"
}
}
<field>
<type>button</type>
<text/>
<htmlAttrs>
<value>Clear</value>
<onclick>resetSeqCode()</onclick>
<class>mainButton</class>
</htmlAttrs>
</field>
There are various types of fields which can be returned with a Request for Additional Information. Some are to display to the user, some are to ask the user for input, some are to aid with processing. Common elements of a field are listed below, but not all fields will have all of them.
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 (as follows) to learn more about possible types. |
fieldID | Any field which requires a value to be returned as part of the MFA Response will have a fieldID 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. |
text | A text label to describe the field. It should be displayed with the field for user prompting. |
The list of fields types is as follows
Type | Description |
---|---|
input |
A text input field. |
password |
A password input field (input is masked) |
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
|
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
|
image |
An image to be displayed. Attributes
|
captcha |
An image containing some random text, combined with a text input where the user must enter the letters in the image. If a captcha field does not have a src attribute, or the src is empty, then it should not be displayed. |
hidden |
A hidden input. Attributes
|
options |
A set of mutually exclusive options to choose between. May be best rendered as a select box or as a set of radio buttons. Attributes
|
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
|
set |
A set is a container for a group of fields which are related, and may be more appropriately displayed as a group. The set itself does not necessarily require any specific rendering. Attributes
|
javascript |
Some javascript code to be included on the page, in an html context. This is usually for convenience of the customer, such as automatically moving the cursor to the next input. For security or other reasons, you may wish to ignore these fields. However, there may be cases where equivalent work functionality will be required, through custom development. |
button |
A button input which will cause some kind of action. Usually linked with some Javascript. |
Customer Initialisation Helper
The “Customer Initialisation Helper” is an approach to integrating with the BankFeeds API in order to initialise a new customer, verify their credentials, and then store their credentials for subsequent use. It can be used as an alternative to the Create Customer API function. The Helper has also been extended to give access to Centrelink data upon request by using the Bankstatements Centrelink API, which will be sent in a seperate stream to the regular bankfeeds data. However because the MyGov login (which is required to access Centrelink online) must utilise multi-factor authentication steps, credentials for Centrelink data are not stored. Note this data can be sent to a callback URL that is also different to the regular BankFeeds callback.
PROCESS STEPS
The process for creating and storing customer credentials via the “Customer Initialisation Helper” is as follows:
- Your application will use the Create Initialisation Link API function to request a unique, time limited link that can be used for a new customer.
- Your application will use one of the URLs provided in the response received from the request in step 1 in order to display the bank selection interface to your customer. You can provide the URL link to the customer in one of several different ways, such as embedded within your site as an iFrame, or via a link in an email/sms etc.
- Your customer can then select their bank/institution, and enter the credentials to log into that bank. The API will then attempt to log into that user’s bank in order to confirm that the credentials are valid.
- Upon a successful submission, the user will then be redirected to a pre-configured redirect URL in order to display a success page (and allow you to take control of any subsequent steps in your sign-up process via your own application). BankFeeds will also submit the stored
customerID
and related information to a pre-configured callback URL. The redirect URL and callback URL will be configured specific to your account with BankFeeds.
Create Initialisation Link
Request
{
"reference": "my-ref",
"link_expiry": 300,
"customer_name": "John Smith",
"return_type": "application/json",
"request_centrelink": false,
"exclude_bankstatements": false,
"redirect_url": "https://example.com",
"user_ref": "my-user-ref",
"request_export_selection": true,
"with_transactions": false
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<reference>my-ref</reference>
<link_expiry>300</link_expiry>
<customer_name>John Smith</customer_name>
<return_type>application/json</return_type>
<request_centrelink>0</request_centrelink>
<exclude_bankstatements>0</exclude_bankstatements>
<redirect_url>https://example.com</redirect_url>
<user_ref>my-user-user_ref</user_ref>
<request_export_selection>true</request_export_selection>
<with_transactions>false</with_transactions>
</xml>
Response
{
"url": "/v1/customer/initialise/eyJ0e...sAJ8",
"iframeUrl": "/v1/customer/initialise/eyJ0e...gIck"
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<url>/v1/customer/initialise/eyJ0e...sAJ8</url>
<iframeUrl>/v1/customer/initialise/eyJ0e...gIck</iframeUrl>
</xml>
DESCRIPTION
This function begins the “Customer Initialisation Helper” process. It will cause the API to generate and return time-limited URLs that can be used to display a user interface for the customer on-boarding process (i.e. the collection of customer credentials and/or the one time collection of Centrelink/MyGov data).
FUNCTION
Request Part | Value |
---|---|
Type | POST |
URL | /customer/initialise |
REQUEST HEADER
Name | Required | Value |
---|---|---|
X-API-KEY | Your API key (see API Keys) | |
Content-Type | The data format of your request (see Request Data Format) | |
Accept | The desired data format of the response (see Response Data Format) | |
X-OUTPUT-VERSION | The desired version of this API function to implement (see API Versions) Supported values:
|
REQUEST BODY
Name | Required | Value |
---|---|---|
reference |
A reference number that you can generate that we will pass back at the end of the process. This can be used to associate the data submitted at the end of the process with the original customer creation request. | |
link_expiry |
A number to determine the amount of time that the generated links can be used to submit a user’s bank credentials. The expiry time is measured in seconds. The links will not be use-able after they expire, and a new request would need to be sent to the API in order to retrieve new URLs. | |
customer_name |
The name of the customer. This will be stored as part of the encrypted user credentials in the BankFeeds API. This field has a maximum length of 200 characters. | |
request_centrelink |
True/False/1/0, Default is False. During the setup process also prompt the customer to provide centrelink data (credentials for this are not saved). | |
exclude_bankstatements |
True/False/1/0, Default is False. Do not request bank credentials as part of this process (no customer id will be created nor any credentials stored). | |
return_type |
The data format to use when sending data to your callback URL. Valid options are application/json (i.e. the default) and application/xml . |
|
redirect_url |
An override for where the customers browser will get redirected to, this field must be a valid absolute URL and has a maximum length of 200 characters. | |
user_ref |
The User Reference tag to be associated with the customer. This will only be used if the Users feature has been activated on your account. | |
request_export_selection |
Default value is false . Set to true in order to display an additional screen to the user after collecting and verifying login details. The additional screen will ask the user to select default accounts for export. |
|
with_transactions |
Default value is false . If set to true , then the data delivered to the callback URL associated with your account will include transaction data. |
|
institution |
This is an optional parameter for which the value should be a bank slug . If this parameter is included then the CIH urls in the return response will display the login screen of the selected bank. This overrides the default functionality of the CIH urls which normally display the bank selection screen. |
RETURN RESPONSE
A successful response will include two URLs that can be used to display to the customer a bank selection interface so that they can select their bank and enter their credentials. Currently two URLs are provided:
- A BankFeeds branded user interface for bank selection, i.e.
url
, and - An un-branded/plain user interface for bank selection, i.e.
iframeUrl
, that is suitable for use in an iFrame to then embed into your website.
Your application will use one of the URLs provided in order to display the bank selection interface to your customer. This can be done by appending the URL of your choice to the base API URL. For example if using the test environment (i.e. https://apitest.bankfeeds.com.au/
) and the url
response parameter, you would combine them to create the URL https://apitest.bankfeeds.com.au/v1/customer/initialise/eyJ0e...sAJ8
.
Once your customer is able to view the bank selection interface, your customer can then select their bank/institution, and enter the credentials to log into that bank. The API will then attempt to log into that user’s bank in order to confirm that the credentials are valid.
If the user submits incorrect credentials they will have one additional attempt to re-submit the correct credential information before their account is temporarily locked in an effort to prevent their bank locking their account.
If the user submits the information correctly, BankFeeds will:
- Submit the details about the stored user credentials to the callback URL (see Submission to Callback, and
- Redirect the user to the provided redirect URL or the pre-determined redirect URL configured on your account if none is provided (see Returning Control)
If the user is requested to make an export selection this will be done before returning the stored user credentials and redirecting the user. Also note that requesting the user to select export accounts does NOT prevent you from accessing other accounts at a later date, but it does set a default selection that will be used if no accounts are specified when refreshing the customer’s transaction data.
Submission to Callback
Callback Response
{
"customerId":"c6113beb...45489edab5e9",
"encryptionKey":"gXzly58H...irFbG0w=",
"reference":"my-ref",
"hasMFA":false
}
<xml>
<customerId>c6113beb...45489edab5e9</customerId>
<encryptionKey>gXzly58H...irFbG0w=</encryptionKey>
<reference>my-ref</reference>
<hasMFA>1</hasMFA>
</xml>
When BankFeeds has confirmed the customer’s credentials, BankFeeds will send the customerId
, encryptionKey
, and the reference number (supplied by you in the initial Create Initialisation Link request) to the callback URL specified for your account. The submitted data will be in the format (i.e. JSON or XML) that was specified via the initial Create Initialisation Link request.
The submission to the callback URL will be a POST
and the raw body of the submission will typically contain similar data to what is returned by the Create Customer API function. However, when a customer required the use of any kind of Multi-Factor Authentication (i.e. a token, SMS codes, or a CAPTCHA), BankFeeds will perform a retrieval of the account details and transactions and will combine that data with the customer credential data, and provide it all as part of the callback response. In this scenario, the response data will be in the same format as what is returned by the Retrieve Customer Data API function.
In the case of Centrelink/MyGov data, the submission will be sent to the centrelink callback URL or if it hasn’t been configured to the callback URL . The data will be sent in a POST
request and will contain similar data to what is returned by the BankStatments Centrelink API with the provided Customer Reference number added to the bottom as well as a document_request_url which can be used to access Centrelink/MyGov documents in the same way as this method from the BankStatements Centrelink API which will also have the customer reference added to the response.
The callback response may contain an additional field storedReusableMfa
which if present will have the value true
. The presence of this field and value indicate that BankFeeds API has stored the reusable MFA data with the customer’s credentials, thereby simplifying future interactions with the API for this customer. This will only occur if the customer initialisation process required the customer to select an account profile or similar as part of a “Request for additional information” step.
Download Centrelink Reports
Request (for Income Statement)
{
"document": "income_statement"
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<document>income_statement</document>
</xml>
Request (for Generated Data Statement)
{
"document": "generated_data"
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<document>generated_data</document>
</xml>
Response
{
"document_title": "XXXX--incomestatement-mygov---YYYYYYYYYY-e.pdf",
"document_data": "JVBERi0xLjcNC ... base64 encoded file data ... cNCiUlRU9GDQo=",
"reference": "my-ref"
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<document_title>XXXX--incomestatement-mygov---YYYYYYYYYY-e.pdf</document_title>
<document_data>JVBERi0xLjcNC ... base64 encoded file data ... cNCiUlRU9GDQo=</document_data>
<reference>my-ref</reference>
</xml>
DESCRIPTION
This function accesses the Bankstatements Centrelink API on your behalf and retrieves the requested Document, the exact link is provided as part of the retrieved Centrelink data, see here for more information.
FUNCTION
Request Part | Value |
---|---|
Type | POST |
URL | /centrelink/token /reports |
REQUEST HEADER
Name | Required | Value |
---|---|---|
X-API-KEY | Your API key (see API Keys) | |
Content-Type | The data format of your request (see Request Data Format) | |
Accept | The desired data format of the response (see Response Data Format) |
REQUEST BODY
Name | Required | Value |
---|---|---|
document |
The document type to retrieve, the available documents are returned as part of the Centrelink data under the Available Documents section. |
RETURN RESPONSE
If the call is successful, then the response will contain a document_title
field that will contain a unique filename for the document, and also a document_data
field that will contain the base64 encoded data for the file. If the call was unsuccessful an error will be returned.
AVAILABLE DOCUMENTS
There are two types of documents that BankStatements can produce and provide for download using this endpoint:
income_statement
This is the Centrelink generated PDF document of the customer’s details and recent payment history.generated_data
This is the BankStatements generated and branded document of the customer’s details and recent payment history.
Returning Control
To allow integrations with BankFeeds to have more control over the finalisation of the customer creation process, BankFeeds can redirect the users to another page/URL on your website. The redirect URL is stored as a part of your integration’s settings within BankFeeds, and will be the same for all requests. This will allow you to display a custom success (or error) message to the user directing them to the “next steps” that are required in the process.
CONDITIONS FOR REDIRECTION
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 the URL used had expired etc.
The API will attempt to perform the redirect on the outermost parent page available (i.e. the javascript top page). In the case that this fails, then just the iFrame itself will be redirected. It is not expected that the top redirect will fail, but the backup is in place, in case there is a change to browser security models or other similar features.
PARAMETERS
The following parameters will be passed in the URL:
referrerCode
- The complete referrer code as set in the iframe URL, including 4 letter client code and any unique client identifier.status
- One of the following values will be provided;COMPLETE
- The process completed successfully.INVALID_TOKEN
- The user has used an invalid link, usually due to link expiry.LOGIN_FAIL
- The user has submitted incorrect credentials two or more times.ERROR
- An error occurred.
If the status is error, then the following two parameters will also be provided
errorCode
- This is normally a 5 digit number. See API Errors for more details.errorText
- This is a text message suitable to show a user about what error has occurred.
Appendix
Additional technical information relating to the BankStatements API can be found within this section:
API Errors
Example error response:
{
"error_code": 40101,
"error_message": "There was an encryption error. The key may be invalid."
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<error_code>40101</error_code>
<error_message>There was an encryption error. The key may be invalid.</error_message>
</xml>
The following error codes and messages can be generated by BankFeeds:
Error Code | Meaning |
---|---|
10101 | Error reading input. |
10102 | Customer not found. |
10103 | A required parameter was not included in the request. |
10104 | The login credentials are not valid. |
10105 | Unable to log in to bank account. Credentials may be incorrect. |
10106 | This function is not available on your account. Please get in touch. |
20101 | Error updating the customer. |
20102 | Error deleting the customer. |
30101 | The API key was not included in the input. |
30102 | A required input was not included. |
30103 | Invalid API key supplied. |
30104 | The request URL was not valid (404 Not Found). |
30105 | This bank was not found. |
30106 | The link that you have used is not valid. |
30107 | The token you are using has now expired. |
30108 | No report files are available for download. |
40101 | There was an encryption error. The key may be invalid. |
50101 | There was an error communicating with the BankStatements service. |
50102 | The institutions is invalid, or we can’t export data from it at this time. |
50103 | An unexpected error occurred. |
50104 | The customer id passed from openbanking consent ui was invalid. |
90101 | Multi-factor authentication is not available for this API call. |
90102 | Banking institution can not be updated via API. Please delete the customer and recreate a new customer with the corrected details. |
91019 | An unknown error occurred. |
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. |
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. |
30014 | There was a temporary error while collecting data. Please try again later. |
30016 | No account parsed successfully. |
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. |
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. |
Bank Account Types
When the API returns a response containing information about a cusomter’s bank account(s), the response may contain an accountType
field that identifies the account type of each bank account. Following is a list of the valid values that may be used to categorise a bank account:
transaction
savings
credit card
personal loan
home loan
car loan
insurance
superannuation
investments
reward card
trading
frequent flyer
shopping reward
Note that it is possible that an empty/blank value is returned if BankFeeds cannot determine the account type for some reason.