Before starting to use the Neonomics API’s Payments or Accounts endpoints you will need to complete these three steps:

1. Create a Neonomics application on the developer portal, to get a Neonomics application Client ID and Secret ID.
2. Authenticate with the Neonomics API, to obtain an access_token so Neonomics can allow you to make requests to the Neonomics API.
3. Create a bank session, allowing you to initiate a session between an end-user and a bank to get accounts data or initiate a payment.

Please make sure to use HTTP 1.1 or above when interacting with the Neonomics platform.

Step 1: Create a Neonomics application

Neonomics requires you to have an access_token to use the Neonomics API. Any requests to Neonomics API without a valid access_token in the headers will return an error.

To get an access_token you need to create an application on the Neonomics Developer Portal. An application represents a client of the Neonomics API that has access to certain services (Accounts and/or Payments). Each Neonomics application has a Client ID and Secret ID which are used every time you want to authenticate with the Neonomics API.

Create an account, confirm your email and login to the Neonomics Developer Portal. You will then be taken to the portal’s dashboard.

Every Neonomics account has a ‘private’ organization that is created when you sign up. It is the default organization on your dashboard. You cannot share your ‘private’ organization with any other user, it is used for creating test applications.

In your ‘private’ organization create a new application. In the second step of creating an application make sure to select both Account Data and Payment Initiation.

The third step of creating an application generates a Client ID and Secret ID. Note: both of these IDs will be required in the next steps.

Step 2: Authenticate with the Neonomics API

Now that you have created a Client ID and Secret ID, you can obtain an access_token. To do this you need to make a POST request to the Neonomics API authentication endpoint.

Use the curl command below to obtain an access_token. You will need to use the Client ID and Secret ID – generated in Step 1 – in place of <CLIENT_ID> and <SECRET_ID>.

Request:

curl -s -X POST <https://sandbox.neonomics.io/auth/realms/sandbox/protocol/openid-connect/token>  
-H "Content-Type: application/x-www-form-urlencoded"  
-d "grant_type=client_credentials"  
-d "client_id=\<CLIENT_ID>"  
-d "client_secret=\<SECRET_ID>"

Neonomics returns the following object.

Response:

{  
    "access_token": "\<ACCESS_TOKEN>",  
    "expires_in": 3600,  
    "refresh_expires_in": 7200,  
    "refresh_token": "\<REFRESH_TOKEN>",  
    "token_type": "bearer",  
    "session_state": "eed85c80-4bd3-4c54-acb6-326075f53070"  
}

Keep a note of the access_token as you will need this for Step 3.

This object also contains a refresh_token and the time it will take for both the tokens to expire. See the authentication guide on how to refresh your tokens.

Step 3: Create a bank session

To use the Payments or Accounts endpoints you need to create a session that maintains a context for all the operations towards a bank for a specific end-user.

When creating a session you will need the three following values:

• access_token - Obtained in step two.
• x-device-id - A string representation of a unique identifier for a single user or device. This could for example be a universally unique identifier (UUID) that you assign. It is used as a header value in all requests to the Neonomics API. In this guide, we use the value example_id_for_quickstart.
• bankId of the bank you wish to create a session for your end-user. You will obtain this value from Neonomics API’s /banks endpoint. This is explained below.

The section below explains how to get a list of banks that are available to connect to through the Neonomics API. Once you have done this you can create a session between that bank and an end-user.

Getting banks

Neonomics API has a banks endpoint that gets all the banks that are available on the Neonomics platform.
This endpoint is used to get the id for the bank that you want to create a session with.

Use the GET request below to get the list of available banks using the access_token you created in Step 2 in place of <ACCESS_TOKEN>.

Request:

curl -X GET <https://sandbox.neonomics.io/ics/v3/banks>  
-H "Authorization:Bearer \<ACCESS_TOKEN>"  
-H "Accept:application/json"  
-H "x-device-id:example_id_for_quickstart"

This request will return an array of bank API objects.

Response:

\[  
    {  
        "countryCode": "NO",  
        "bankingGroupName": "DNB Group",  
        "personalIdentificationRequired": true,  
        "id": "RG5iLm5vLnYxRE5CQU5PS0s=",  
        "bankDisplayName": "DNB",  
        "supportedServices": [  
            "accounts",  
            "domestic-transfer"  
        ],  
        "bic": "DNBANOKK",  
        "bankOfficialName": "DNB ASA",  
        "status": "AVAILABLE"  
    },  
    {  
        "countryCode": "SE",  
        "bankingGroupName": "SEB Group",  
        "personalIdentificationRequired": false,  
        "id": "c2ViLnN3ZWRlbi52MUVTU0VTRVNT",  
        "bankDisplayName": "SEB",  
        "supportedServices": [  
            "accounts",  
            "domestic-transfer",  
            "domestic-scheduled-transfer",  
            "sepa-credit",  
            "sepa-scheduled-credit"  
        ],  
        "bic": "ESSESESS",  
        "bankOfficialName": "Skandinaviska Enskilda Banken AB",  
        "status": "AVAILABLE"  
    },  
    {  
        "countryCode": "FI",  
        "bankingGroupName": "S-Bank Ltd",  
        "personalIdentificationRequired": false,  
        "id": "c3BhbmtraS52MVNCQU5GSUhI",  
        "bankDisplayName": "S-Pankki",  
        "supportedServices": [  
            "accounts",  
            "sepa-credit"  
        ],  
        "bic": "SBANFIHH",  
        "bankOfficialName": "S-Banken Ab",  
        "status": "AVAILABLE"  
    },  
    {  
        "countryCode": "NO",  
        "bankingGroupName": "",  
        "personalIdentificationRequired": false,  
        "id": "anVzdG9iYW5rLnYxSlVTVE5PS0s=",  
        "bankDisplayName": "Justo Bank",  
        "supportedServices": [  
            "accounts",  
            "sepa-credit"  
        ],  
        "bic": "JUSTNOKK",  
        "bankOfficialName": "",  
        "status": "AVAILABLE"  
    },  
    {  
        "countryCode": "NO",  
        "bankingGroupName": "Sbanken",  
        "personalIdentificationRequired": false,  
        "id": "U2Jhbmtlbi52MVNCQUtOT0JC",  
        "bankDisplayName": "Sbanken",  
        "supportedServices": [  
            "sepa-credit",  
            "domestic-transfer",  
            "accounts"  
        ],  
        "bic": "SBAKNOBB",  
        "bankOfficialName": "Sbanken ASA",  
        "status": "AVAILABLE"  
    },  
    {  
        "countryCode": "NO",  
        "bankingGroupName": "",  
        "personalIdentificationRequired": false,  
        "id": "aGl6b250aWJhbmsudjFISVpPTk9LSw==",  
        "bankDisplayName": "Hizonti Bank",  
        "supportedServices": [  
            "accounts",  
            "sepa-credit"  
        ],  
        "bic": "HIZONOKK",  
        "bankOfficialName": "",  
        "status": "AVAILABLE"  
    }  
]

Creating a session

Now that you have the id of the available banks, you can create a session between your end-user and the bank.

Use the flowing command to generate a session. Use the access_token you created in Step 2 in place of <ACCESS_TOKEN>. You also need a bankId. In this example, we are using the bankId for a bank called Sbanken.

Request:

curl -X POST <https://sandbox.neonomics.io/ics/v3/session> \\  
-H "Authorization:Bearer \<ACCESS_TOKEN>" \\  
-H "x-device-id:example_id_for_quickstart" \\  
-H "Content-Type:application/json" \\  
-d '{"bankId": "SGFuZGVsc2Jhbmtlbi5ub3J3YXkudjFIQU5ETk9LS1hYWA=="}'

This request will return a sessionId as follows.

Response:

{  
  "sessionId": "\<SESSION_ID>"  
}

Great work! You now have a sessionId that can be used to integrate with Neonomics Accounts and Payments. 😺