Quickstart Guide

This document explains how to jump-start your integration with the Account Information API. 


Step 1: Get Access Token

First, you'll need to get your token from Nordigen's Open Banking Portal.


Step 2: Choose a Bank

Use aspsps endpoint to get a list of all available ASPSPs (banks) in a given country. You will need to provide an access token from Step 1 as YOUR_TOKEN and a two-letter country code (ISO 3166). ID for the chosen bank will be used in the following steps (referenced as aspsp_id). See also the guide on how to build an end user interface for selecting a bank.

curl -X GET "https://ob.nordigen.com/api/aspsps/?country=gb" 
-H  "accept: application/json" 
-H  "Authorization: Token YOUR_TOKEN"

Response:

[
  {
    "id": "MONZO_MONZGB2L",
    "name": "Monzo Bank Limited",
    "bic": "MONZGB2L",
    "countries": [
      "GB"
    ]
  },
[...]
  {
    "id": "HSBC_HBUKGB4B",
    "name": "HSBC Personal",
    "bic": "HBUKGB4B",
    "countries": [
      "GB"
    ]
  }
]

Step 3: Create an end-user agreement

N.B. Use this step only if you want to specify the length of transaction history you want to retrieve. If you skip this step, by default 90 days of transaction history will be retrieved.

You need to create an agreement and pass:

  • max_historical_days as the length of the transaction history to be retrieved;
  • enduser_id - a unique end-user ID of someone who's using your services, it has to be unique within your solution. Usually, it's UUID;
  • aspsp_id from Step 2.
curl -X POST 
"https://ob.nordigen.com/api/agreements/enduser/" 
-H  "accept: application/json" 
-H  "Content-Type: application/json" 
-H  "Authorization: Token YOUR_TOKEN"
-d "{  \"max_historical_days\": \"30\", \"enduser_id\": \"8234e18b-f360-48cc-8bcf-c8625596d74a\",  \"aspsp_id\": \"SWEDBANK\"}"

Response:

{
  "id": "2dea1b84-97b0-4cb4-8805-302c227587c8",
  "created": "2020-11-21T07:28:59.065940Z",
  "accepted": null,
  "max_historical_days": 30,
  "access_valid_for_days": 90,
  "enduser_id": "8234e18b-f360-48cc-8bcf-c8625596d74a",
  "aspsp_id": "SWEDBANK"
}

Step 4.1: Create a requisition

First, you need to create a requisition which is a collection of inputs for creating links and retrieving accounts. For requisition API requests you will need to provide:

  • Access token from Step 1 as YOUR_TOKEN;
  • enduser_id - a unique end-user ID of someone who's using your services, it has to be unique within your solution. Usually, it's a UUID NB!If you didn't skip Step 3, the enduser_id has to match one provided in Step 3;
  • reference (additional layer of unique ID defined by you);
  • redirect URI where the end user will be redirected after finishing authentication in ASPSP;
  • agreements as an array of ID(s) from Step 3 or an empty array if you skipped that step;
  • user_language (optional) to enforce a language for all end user steps hosted by Nordigen passed as a two-letter country code (ISO 639-1). If user_language is not defined a language set in browser will be used to determine language.
curl -X POST "https://ob.nordigen.com/api/requisitions/" 
-H  "accept: application/json" 
-H  "Content-Type: application/json" 
-H  "Authorization: Token YOUR_TOKEN" 
-d "{  \"redirect\": \"http://www.yourwebpage.com\",
\"reference\": \"124151\",  \"enduser_id\": \"8234e18b-f360-48cc-8bcf-c8625596d74a\",  \"agreements\": [ \"2dea1b84-97b0-4cb4-8805-302c227587c8\" ], \"user_language\":\"LV\" }"

Response:

{
  "id": "8126e9fb-93c9-4228-937c-68f0383c2df7",
  "redirect": "http://www.yourwebpage.com",
  "status": "CR",
  "agreements": ["2dea1b84-97b0-4cb4-8805-302c227587c8"],
  "accounts": [],
  "reference": "124151",
  "enduser_id": "8234e18b-f360-48cc-8bcf-c8625596d74a",
  "user_language": "LV"
}

Save the requisition ID (id in the response). You will later need it to retrieve the list of end-user accounts.

Step 4.2: Build a Link

Create a redirect link for the end user to ASPSP. You need to provide aspsp_id from Step 2 (and Step 3 if you did not skip it).

curl -X POST "https://ob.nordigen.com/api/requisitions/8126e9fb-93c9-4228-937c-68f0383c2df7/links/" 
-H  "accept: application/json" 
-H  "Content-Type: application/json" 
-H  "Authorization: Token YOUR_TOKEN" 
-d "{  \"aspsp_id\": \"SWEDBANK\"}"

Response:

{
  "initiate": "https://ob.nordigen.com/psd2/start/8126e9fb-93c9-4228-937c-68f0383c2df7/SWEDBANK"
}

Follow the initiate link to start the end-user authentication process with the ASPSP.


Step 5: List accounts

Once the user is redirected back to the link provided in Step 4.1, the user's bank accounts can be listed. Pass the requisition ID to view the accounts.

curl -X GET "https://ob.nordigen.com/api/requisitions/8126e9fb-93c9-4228-937c-68f0383c2df7/" 
-H  "accept: application/json" 
-H  "Authorization: Token YOUR_TOKEN" 

Response:

{
  "id": "8126e9fb-93c9-4228-937c-68f0383c2df7",
  "status": "CR",
  "agreements": [
    "2dea1b84-97b0-4cb4-8805-302c227587c8"
  ],
  "accounts": [
    "065da497-e6af-4950-88ed-2edbc0577d20",
    "bc6d7bbb-a7d8-487e-876e-a887dcfeea3d"
  ],
  "reference": "124151",
  "enduser_id": "8234e18b-f360-48cc-8bcf-c8625596d74a"
}

Step 6: Access accounts, balances, and transactions

There are three separate endpoints for accessing account details, balances, and transactions. See account endpoints to view respective endpoints.

In this quickstart, we will showcase the transactions endpoint, where you need to pass the account ID (see "accounts" from the output of Step 5) to access transaction information. You will need to query each account separately.

curl -X GET "https://ob.nordigen.com/api/accounts/065da497-e6af-4950-88ed-2edbc0577d20/transactions/" -H  "accept: application/json" -H  "Authorization: Token YOUR_TOKEN"

Response:

{
  "transactions": {
    "booked": [
      {
        "transactionId": "2020103000624289-1",
        "debtorName": "MON MOTHMA",
        "debtorAccount": {
          "iban": "GL53SAFI055151515"
        },
        "transactionAmount": {
          "currency": "EUR",
          "amount": "45.00"
        },
        "bankTransactionCode": "PMNT",
        "bookingDate": "2020-10-30",
        "valueDate": "2020-10-30",
        "remittanceInformationUnstructured": "For the support of Restoration of the Republic foundation"
      },
      {
        "transactionId": "2020111101899195-1",
        "transactionAmount": {
          "currency": "EUR",
          "amount": "-15.00"
        },
        "bankTransactionCode": "PMNT",
        "bookingDate": "2020-11-11",
        "valueDate": "2020-11-11",
        "remittanceInformationUnstructured": "PAYMENT Alderaan Coffe"
      }
    ],
    "pending": [
      {
        "transactionAmount": {
          "currency": "EUR",
          "amount": "10.00"
        },
        "valueDate": "2020-11-03",
        "remittanceInformationUnstructured": "Reserved PAYMENT Emperor's Burgers"
      }
    ]
  }
}
      

What's next.

Congratulations - you now can connect to end-user bank accounts and access raw account and transaction data. To learn more about the output data structures and see more details behind the keys, please visit accounts and transactions.

Note: although the ASPSPs are supposed to follow the same recommendations in terms of data structures, this is not always the case. We're filling in the gaps as much as possible, but you should anticipate situations where the amount of data delivered differs between banks, e.g., some banks may include ownerName with the account details, some may opt not to do this. If you spot any specific issues, please don't hesitate to contact us!

Once you’re ready to extract more value from the raw account information, take a look at our premium products - Transaction Categorisation and Insights