Getting started overview

Integrating with Nordigen involves a sequence of steps designed to enable access to open banking data. The initial phase focuses on establishing a developer account and securing the necessary API credentials. Following this, developers authenticate with the Nordigen API to obtain an access token, which is then used to initiate the data retrieval process. This typically includes creating an end-user agreement and establishing a connection to a financial institution through a Nordigen-provided link. Once connected, account and transaction data can be accessed and processed.

Nordigen's API is RESTful and supports various programming languages through official SDKs, including Python and Node.js SDKs. The platform offers a free tier for limited usage, allowing developers to test integrations before scaling.

Here is a quick reference table summarizing the initial steps:

Step What to Do Where
1. Sign Up Create a Nordigen developer account. Nordigen Quickstart Guide
2. Get Keys Generate a secret ID and key for API authentication. Nordigen Quickstart Guide
3. Get Access Token Exchange your secret ID and key for an access token. Nordigen Access Token Documentation
4. Create Agreement Establish an end-user agreement (requisition). Nordigen Requisition Guide
5. Link Bank Generate a link for the end-user to connect their bank. Nordigen Bank Linking Documentation
6. Fetch Accounts Retrieve account details after bank connection. Nordigen Account IDs Documentation

Create an account and get keys

To begin using Nordigen, developers must first register for a developer account. This process is initiated on the Nordigen website and requires basic information to set up the account. Upon successful registration, access to the Nordigen Dashboard is granted, which serves as the central hub for managing projects and API credentials.

Within the Dashboard, a new project needs to be created. Each project is associated with a unique set of API keys, specifically a SECRET ID and a SECRET KEY. These keys are fundamental for authenticating all subsequent API requests. The SECRET KEY is a sensitive credential and should be treated with the same security measures as passwords, never hardcoded directly into client-side code or exposed publicly.

The steps to obtain these keys are:

  1. Sign Up: Navigate to the Nordigen signup page and complete the registration form.
  2. Create a Project: Once logged into the dashboard, create a new project. This action will generate the required API credentials.
  3. Retrieve Keys: Locate your SECRET ID and SECRET KEY within the project settings. The SECRET KEY is typically visible only once upon generation, so it is crucial to store it securely.

These credentials will be used to obtain an access token, which then authenticates requests to the various Nordigen API endpoints, such as those for retrieving account information or managing requisitions.

Your first request

The initial API request with Nordigen involves obtaining an access token. This token is a JSON Web Token (JWT) that authenticates your application for a limited time (typically 24 hours). It is retrieved by sending a POST request to the /token/new/ endpoint with your SECRET ID and SECRET KEY.

Here's an example using curl to get an access token:

curl -X POST https://bankaccount-data.gocardless.com/api/v2/token/new/ \
  -H 'Content-Type: application/json' \
  -d '{
    "secret_id": "YOUR_SECRET_ID",
    "secret_key": "YOUR_SECRET_KEY"
  }'

A successful response will include an access token, a refresh token, and the access_expires timestamp. The access token should be included in the Authorization header of subsequent requests, prefixed with Bearer.

After obtaining the access token, the next step is to create an end-user agreement, also known as a requisition. This is a crucial step in the open banking flow as it represents the user's consent for their data to be accessed. The API call for this involves sending a POST request to the /requisitions/ endpoint:

curl -X POST https://bankaccount-data.gocardless.com/api/v2/requisitions/ \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -d '{
    "redirect": "http://localhost/callback",
    "institution_id": "YOUR_INSTITUTION_ID",
    "user_language": "EN"
  }'

Replace YOUR_ACCESS_TOKEN with the token received in the previous step, and YOUR_INSTITUTION_ID with the identifier of the desired financial institution (e.g., REVOLUT_RVSBGB2L for Revolut). A list of available institutions can be retrieved from the Nordigen Institutions API endpoint. The redirect URL is where the user will be sent after authenticating their bank account.

The response to the requisition creation will include a link parameter. This link is what your application presents to the end-user, allowing them to securely connect their bank account through Nordigen's interface. Upon successful connection, the user is redirected to your specified redirect URL, usually with a ref parameter indicating the requisition ID.

Finally, to fetch account data, you would use the requisition ID to get a list of account IDs, and then query specific accounts. For example, to get account IDs associated with a requisition:

curl -X GET https://bankaccount-data.gocardless.com/api/v2/requisitions/YOUR_REQUISITION_ID/ \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

This will return an array of accounts. You can then retrieve details or transactions for a specific account using its ID:

curl -X GET https://bankaccount-data.gocardless.com/api/v2/accounts/YOUR_ACCOUNT_ID/details/ \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

These initial requests establish the basic flow for interacting with the Nordigen API to access financial data.

Common next steps

After successfully making your first API calls, several common next steps help in building out a robust integration with Nordigen:

  • Explore Data Endpoints: Beyond basic account details, Nordigen offers endpoints for account transactions and balances. Understanding these allows for comprehensive data retrieval.
  • Implement Webhooks: For real-time updates on account activities or the status of requisitions, implement webhooks. This pushes notifications to your application instead of requiring constant polling, improving efficiency. The Nordigen webhooks documentation provides details on setup.
  • Error Handling: Implement robust error handling mechanisms to gracefully manage API rate limits, invalid credentials, institution-specific errors, or consent expirations. Refer to the Nordigen API reference for error codes.
  • SDK Utilization: For developers using Python, Node.js, Java, PHP, Ruby, or Go, leveraging the official Nordigen SDKs can streamline development by abstracting HTTP requests and handling authentication.
  • Refresh Tokens: Implement logic to refresh access tokens before they expire using the refresh token obtained during the initial token generation. This ensures continuous access to the API without requiring re-authentication with secret keys. The Nordigen token refresh endpoint is used for this purpose.
  • Secure Production Deployment: When moving to a production environment, ensure all API keys and tokens are stored securely, preferably using environment variables or a secrets management service. Adhere to OAuth 2.0 Bearer Token best practices for token handling.
  • Compliance and Consent Management: Given Nordigen's focus on open banking, ensure your application adheres to relevant data protection regulations like GDPR. This includes clear consent flows for end-users and transparent data usage policies.

Troubleshooting the first call

Encountering issues during the initial API calls is common. Here are some troubleshooting tips for your first Nordigen API request:

  • Invalid Credentials: Double-check your SECRET ID and SECRET KEY for typos. Ensure you are using the correct credentials for the specific project you created in the Nordigen Dashboard. If you suspect your keys are compromised or incorrect, you can generate new ones within the dashboard.
  • Authorization Header Format: Verify that the Authorization header for subsequent requests is correctly formatted as Bearer YOUR_ACCESS_TOKEN. A common mistake is omitting the Bearer prefix or including extra spaces.
  • Expired Access Token: Access tokens have a limited lifespan (e.g., 24 hours). If you receive an error indicating an invalid or expired token, generate a new one using your SECRET ID and SECRET KEY. For long-running applications, implement the token refresh mechanism.
  • Incorrect Endpoint URL: Confirm that you are sending requests to the correct Nordigen API endpoints. The base URL for the Account Information API is https://bankaccount-data.gocardless.com/api/v2/.
  • Content-Type Header: For POST requests, ensure the Content-Type: application/json header is set correctly, especially when sending JSON bodies.
  • Firewall or Network Issues: If requests are not reaching the Nordigen API at all, check for local firewall rules or network proxy settings that might be blocking outbound HTTPS connections.
  • Institution ID: When creating a requisition, ensure the institution_id is valid and available for your region. You can retrieve a list of supported institutions via the Nordigen Institutions API.
  • Redirect URL Mismatch: The redirect URL specified when creating a requisition must exactly match one of the redirect URLs configured in your Nordigen project settings. A mismatch will prevent the user from being redirected correctly after bank authentication.
  • Review API Documentation: The Nordigen API Reference provides detailed information on expected request formats, response structures, and error codes. Consulting it can often clarify specific issues.
  • Consult Nordigen Support: If you've exhausted all troubleshooting steps, Nordigen provides support channels, typically accessible through their developer portal or documentation, for further assistance.