Accounts
How to fetch account data using the Neonomics API.
To get account data you will need to complete these two steps:
- Fetching accounts using the accounts endpoint to get an array of end-user accounts.
- Getting transactions by using an account id and the transactions endpoint.
Info
You need to complete the development quickstart and the customer consent guide before starting this guide. A valid access_token and sessionId are needed to follow this guide.
Step 1: Fetching accounts
To fetch accounts API, you will need to make a GET request to the /accounts/ Neonomics API endpoint. This endpoint is used to get all the accounts associated with a session. A sessionId is the link between an end-user and a bank.
Use the curl GET request below to fetch the accounts. You will need to use the access_token and sessionId – generated in the Development quickstart – in place of <ACCESS_TOKEN> and <SESSION_ID>.
The endpoint uses the header parameter x-psu-ip-address, which contains the end-user's IP address. It is required if the end-user is requesting the account data. If it is a background refresh request then the x-psu-ip-address can be empty.
PSU is an acronym of Payment Service User, which is an end-user. The term is used in PSD2 contexts.
Request:
curl -X GET <https://sandbox.neonomics.io/ics/v3/accounts>
-H "Authorization:Bearer \<ACCESS_TOKEN>"
-H "Accept:application/json"
-H "x-device-id:example_id_for_quickstart"
-H "x-psu-ip-address:109.74.179.3"
-H "x-session-id:\<SESSION_ID>"
Please note that bank details used in this document are test details which are only used in the sandbox.
Below are two example responses to the request above, both with the status code 200.
You will, in some cases, instead get a response with the status code 510 together with error code 1426, which means that end-user consent is required. Our Consent guide gives an example of how to get end-user consent in such cases.
Response examples:
[
{
"id": "ACCOUNT_1_ID",
"iban": "NO2390412263056",
"bban": "90412263056",
"accountName": "Daily account",
"accountType": "TAXE",
"ownerName": "Joanna Doe",
"displayName": "My account",
"balances": [
{
"amount": "9049.32",
"currency": "NOK",
"type": "CLSG"
},
{
"amount": "10000",
"currency": "NOK",
"type": "EXPN"
}
]
}
]
[
{
"id": "ACCOUNT_2_ID",
"iban": "GB29NWBK60161331926819",
"bban": "NWBK60161331926819",
"sortCodeAccountNumber": "60161331926819",
"accountName": "Current account",
"accountType": "CACC",
"ownerName": "João Doe",
"displayName": "Conta corrente",
"balances": [
{
"amount": "10000",
"currency": "GBP",
"type": "CLSG"
},
{
"amount": "11086.17",
"currency": "GBP",
"type": "EXPN"
}
]
}
]
This response contains an array of accounts API objects for the sessionId used in the curl request. The balances attribute is an array of balance objects. Each one has a type attribute that is an ISO code that represents the type of balance. A bank account can have multiple balances for example:
CLSG- The balance at the end of the bank’s business day.AVLB- The balance that is at the disposal of the account owner at that date specified.
Save an account id from the response above. It will be needed in the next step.
Step 2: Getting transactions
Now that you have a list of your end-user's bank accounts, you can get the accounts' transactions.
To fetch transactions API, you will need to make a GET request to the /accounts/<ACCOUNT_ID>/transactions Neonomics API endpoint. This endpoint is used to get all the transactions for a specific account.
Use the curl GET request below to fetch the account transactions. You will need to use the access_token and sessionId – generated in the Development quickstart – in place of <ACCESS_TOKEN> and <SESSION_ID>.
Also, you will need to replace the<ACCOUNT_ID> in the URL with the account id generated in step one.
Request:
curl -X GET <https://sandbox.neonomics.io/ics/v3/accounts/>\<ACCOUNT_ID>/transactions
-H "Authorization:Bearer \<ACCESS_TOKEN>"
-H "Accept:application/json"
-H "x-device-id:example_id_for_quickstart"
-H "x-psu-ip-address:109.74.179.3"
-H "x-session-id:\<SESSION_TOKEN>"
Below is an example response similar to the one returned from the request above. It is an array of transactions for the account id you provided in the curl requests URL.
Response:
[
{
"id": "TRANSACTION_1_ID",
"transactionReference": "Credit interest",
"transactionAmount":
{
"currency": "NOK",
"value": "10.59"
},
"creditDebitIndicator": "CRDT",
"bookingDate": "2021-08-31T00:00:00.000Z",
"valueDate": "2021-08-31T00:00:00.000Z",
"bookingDate": "2021-08-31T00:00:00.000Z",
"valueDate": "2021-08-31T00:00:00.000Z",
"counterpartyAccount": "DE89370400440532013000",
"counterpartyName": "Farmer's bank",
"counterpartyAgent": "HASPDEHHXXX"
},
{
"id": "<TRANSACTION_2_ID>",
"transactionReference": "Salary",
"transactionAmount":
{
"currency": "NOK",
"value": "59000.0"
},
"creditDebitIndicator": "CRDT",
"bookingDate": "2021-09-15T00:00:00.000Z",
"valueDate": "2021-09-15T00:00:00.000Z",
"counterpartyAccount": "",
"counterpartyName": "Economy dept.",
"counterpartyAgent": ""
},
{
"id": "<TRANSACTION_3_ID>",
"transactionReference": "Instalment",
"transactionAmount":
{
"currency": "NOK",
"value": "1000.0"
},
"creditDebitIndicator": "DBIT",
"bookingDate": "2021-09-15T00:00:00.000Z",
"valueDate": "2021-09-15T00:00:00.000Z",
"valueDate": "2021-09-15T00:00:00.000Z",
"counterpartyAccount": "DE89370400440532013000",
"counterpartyName": "The building society",
"counterpartyAgent": "AAAABBCCXXX"
}
]
Brilliant! You have now fetched account and transaction data for one end-user bank account 🏄♀️
Updated 7 months ago