Tips, Tricks and Best Practices

1. Be aware of paging

Each end-point that returns multiple records in the SISS REST APIs use pagination to return results.

Query Parameters

The pagination requirements are stipulated on a request using query parameters. For end-points that support paging the following query parameters MAY be provided:

page – the page number being requested (with the first page being 1)
page-size – the number of records to return in each page

If the query parameters are not provided the following defaults will be assumed:

page – a default of 1 (the first page) will be assumed
page-size – a default of 25 will be assumed

Response Fields

In addition to the data requested, the responses include following additional information:

In the links object, in addition to the self field the following fields are to provided:
- first - A URI to request the first page. Only returned if this response is not the first page.
- last - A URI to request the last page. Only returned if this response is not the last page.
- prev - A URI to the previous page. Only returned if this response is not the first page.
- next - A URI to the next page. Only returned if this response is not the last page.
In the meta object the following fields are to be provided:
- totalRecords - The total number of records in the set.
- currentpage - The current page of the set.
- totalPages - The total number of pages in the set.

Additional Info

A maximum page size of 500 records is set for all end points. If a page size greater than this maximum is requested then a HTTP status of 422 Unprocessable Entity WILL be returned.

2. Cater for Rate Limiting (Throttling)

Rate Limits are in place for all tiers (even the unlimited tier has an upper maximum TPS). You should control the number of calls you make to the SISS REST APIs to match the TPS and monthly limits of your subscribed products.

If you make more than your allowed calls within 1 second, or exceed your total calls for the month, you will receive a 429 Too Many Requests response. This response includes a retry-after field, which states the number of seconds you need to wait.

You DO NOT need to request a new JWT token upon receiving this error, and making a call with a new token (assuming you could retrieve a new JWT token within the retry-after value) will return the same error code.

3. Use a Unique ID that represents your client when adding Accounts

To make it easy for you to manage your data within the SISS API, and to assist you with matching data within your systems, when creating Accounts, we strongly recommend providing an (obfuscated) identifier that represents your client which you pass to either:

/sds/account-access-consents/consumerconsent as a clientId body parameter
/sds/account-access-consents/consumerconsent as the clientIdentifier body parameter

4. Track the last transaction ID received for each account

Any time you retrieve transactions, you SHOULD store the most recent transaction ID received for the account against the account record in your system.

The reason to do this, is to make your calls as efficient as possible, so you are only collecting only new transactions. As all data provided to SISS is POSTED transactions up until midnight of the previous day, transaction IDs only increment.

Alternatively, you could use the last transaction date retrieved (ie the most recent date of a transaction stored against the account in your system). You could then just retrieve data from that date forward.

5. Allow for recollection of data and use transaction ID for deduplication.

There may be cases where a client may want to recollect data for dates which have already been collected.

If data is recollected, you should use the transaction ID to prevent inserting duplicate transactions into your stored transactions.

6. Collect data in an efficient manner

The SISS REST API's allow you to collect data in bulk for all your customers, or collect in a more targeted manner. Choose the method that is effective for you.

Bulk Collection

This allows you to collect data in paged data sets, and then match data up within your systems.

The typical set of calls would be:

Get a List of All Clients - /sds/clients
Check that you know all the clients you need to be matching data against.
Get a List of All Accounts - /banking/accounts
A list of all accounts available to you. This account list includes, for each account, any clientId you provided in Tip 3 above. Note, this also includes a field high
Get a List of All Balances - /banking/accounts/balances?x-v=2
A list of all balances available to you. This balance list includes, for each balance, the accountId the balance relates to. We recommend providing the x-v=2 parameter to get a list which has a format aligned to CDR version 1.
For each account in the List of All Accounts - Get a List of Transactions for an Account - /banking/accounts/{accountId}/transactions?{oldest-time}
A list of transactions for a specific account. If you have followed Tip 4 above, you SHOULD also only request transactions for accounts where you know there are new transactions (by checking the value stored in your system against the lastTransactionPostedDate field in the account record)

On-demand/Targeted

This relies on getting the data for clients based on the clientId, assuming you have followed Tip 3 above

(Optional) Get a List of All Clients - /sds/clients
Used to check in case any clients have been disabled or added that you have not tracked. Also you can do this if you dont have the clientId in your systems.
Get a List of Accounts for a Client - /sds/clients/{clientId}/accounts
Used to check in case any accounts have been disabled or added that you have not tracked. If you supplied your clientId as per Tip 3, then you can get a list of accounts for just that client.
For each account in the List of Accounts for a Client - Get Balances for an Account - /banking/accounts/{accountId}/balances?x-v=2
A list of balances for the account. We recommend providing the x-v=2 parameter to get a list which has a format aligned to CDR version 1.
For each account in the List of Accounts for a Client - Get a List of Transactions for an Account - /banking/accounts/{accountId}/transactions?{oldest-time}
A list of transactions for a specific account. If you have followed Tip 4 above, you SHOULD also only request transactions for accounts where you know there are new transactions (by checking the value stored in your system against the lastTransactionPostedDate field in the account record)

7. Valid BSB and Account numbers

Before submitting requests to register bank data feeds, please use local validation to validate the BSB and Account Numbers entered by clients. These are the same rules that are enforced by the SDS system. All valid BSB are 6 digits in length, the 3rd digit must be in range [2-7], each of which represents a unique ‘State Code’ (i.e. NSW, QLD, VIC)

BSB General rules

While there are some specific rules for each bank (listed below). We also validate each BSB and it must be an active & valid BSB per Australia Payments Network (AUSPAY), even if the BSB passes the rules below, should the BSB not be on the AusPay list we will return an error. Please note some of the BSB's on this list are not actual branches rather internal, test, agency or some other special purpose, as such we may fail some of these BSB's, also we have another list of 'acceptable' BSB's that customers can use even although they may not be on the AusPay list, should you come across a BSB we did not allow, please email us the details at customerservice@siss.com.au

Link to website of 'offical' BSB's https://bsb.auspaynet.com.au/public/BSB_DB .NSF/publicBSB.xsp

ANZ - Australia New Zealand Bank

BSB length = 6, Starts with 01

Account Number length 9

Bank of Melbourne

BSB length = 6 Starts with '19' OR '55'

Account Number length 9

Bank SA

BSB length = 6 Starts with '10'

Account Number length 9

CBA - Commonwealth Bank of Australia

BSB length = 6 Starts with '06' OR '76'

Account Number length 8

Not available if starts with 5 = term deposit

Macquarie Bank

BSB length = 6 Starts with '18'

Account Number length 9, and the account number starts with a 1 or 9

NAB - National Australia Bank

BSB length = 6 Starts with '08' OR '78'

Account Number length 9

St George

BSB length = 6 Starts with '11' OR ‘33’

Account Number length 9

Westpac

BSB length = 6 Starts with '03' OR '73'

Account Number length 6

Bank of Queensland

BSB length = 6 Starts with ‘12’

Account Number length 7-10

Adelaide Bank

BSB length = 6 Always ‘610101’

Account Number length 9

8. Special Commands & Functions

When a bank account is added to the ACSISS service via a authorise consent post, it changes status from (C)reated to (R)eceived to (A)ctive while spending a random amount of time (between 5 & 30 minutes) at each status. Each day the bank account remains active, an arbitrary number of transactions will be added (up to 10) for random values.

The following commands can alter the above behaviour by adding a PREFIX to the accountName.

(FAST) - This will speed up the changing of status to a random interval of time between 30 & 60 seconds, meaning it will be active within 3 minutes
(FAST=x) - This will speed up the changing of status every x minutes, if you set x=0 then the feed will be active effectively immediatley.
(HIST) - Loads a predefined set of 2135 transactions for the previous 61 days at an average of 35 transactions per day
(STATIC) - will create two transactions each the feed remains active, one payment & one deposit for $100, meaning the account balance remains static.
`(REJ) - This will move the status from (C)reated to (R)eceived to (P)roblem. This rejection mimics the situation of a Bank not approving the bank feed. Rejected feeds also have no auto-generated transaction data
(SAP) or (JIWA7) Loads a predefined set of transactions specific to the demonstration data in those ERP solutions.

Some of these PREFIXES can be stacked to achieve specific tasks; for example (FAST,HIST) will move the feed to active quickly and load the historical transaction data.

"accountName": "(FAST, HIST) Account Name" - This account will be created with 61 days of historical data, and will go from ‘C’ to ‘R’ to ‘A’ in about 3-5 minutes. Every day random transactions will be added.
"accountName": "(FAST=0, HIST) Account Name" - This account will be created with 61 days of historical data, and will go from ‘C’ to ‘A’ immediately. Every day random transactions will be added.
"accountName": "(FAST, HIST, STATIC) Account Name" - This account will be created with 61 days of historical data, and will go from ‘C’ to ‘R’ to ‘A’ in about 3-5 minutes. Every day a +$10 and a -$10 transaction will be added. The balance will not change.
"accountName": "(FAST, REJ) Account Name" - This account will be created and will go from ‘C’ to ‘R’ to ‘P’ in about 2-3 minutes. A problem message will also be populated on the account record.

NOTE: Data feeds in the Sandbox are only maintained for 100 days, that is 101 days after a feed was created it will be removed along with all its transactions.

An example of these commands in the body of a Authorise Account post

"sdsinstitutionId": "ANZ",

"clientIdentifier": "HWSMSF",

"clientName": "Hello World SMSF",

"accountName": "(FAST=0,HIST) Current Account",

"bsb": "012012",

"accountNumber": "985654159"