To see the Neonomics API in action you can use Postman, a multi-platform REST client that enables testing of HTTP requests and viewing responses.

The Neonomics Postman Collection is a group of saved API requests organized into folders. This collection is prepared to support testing of all endpoints in the sandbox environment for the Neonomics platform.

You can find an overview of the endpoints in the API Quick reference documentation, while API References describes everything in detail. The API Flow page gives a visual overview of the sequence of calls and processing logic in the most common scenarios.

Before you can start experimenting with our payment initiation and account information services, you have to make some preparations. These are described in the steps below.

If you prefer any other tool than Postman, it should be possible to adapt the steps below to your preferred tool, since the general procedure is the same.

Preparations

Step 1: Run the Neonomics Postman collection

Import the Swagger file you have received from the Neonomics Customer Success team into Postman.

Step 2: Get your client ID and secret ID

If you already signed up for the Neonomics Developer Portal and created at least one application, go to your portal Dashboard, select an application and find the IDs, so you have them ready for the next step.

If you haven't signed up yet, do it now and then create an application as described in the first step of our Quickstart guide.

Step 3: Set initial variables

You need to save your client ID and secret ID as variables before you can start making requests with the Neonomics Postman collection. This is how you do it:

1. Under Collections in the Postman User Interface, hover over the Neonomics API collection and click on the ... symbol (View more actions) and then select Edit.
2. In the EDIT COLLECTION pop-up window, select Variables.
3. Enter your client ID and secret ID in the fields client_id and client_secret in the CURRENT VALUE column.
4. Click Update.

Step 4: Obtain your access token

Before you can make any other requests, you need to obtain your access token with a Token request API:

1. Select the POST Token request in the Authentication folder in the Neonomics API collection in Postman.
2. Click Send.
3. You should get a 200 OK response status, and both the access token and the refresh token will automatically be saved in Variables.

📘

Info

Note that you may have to run a Refresh token request at a later stage, as the token expires after a certain period.

Step 5: Select bank

Before you can send requests for account information or payment initiation, you need to select a bank to work with. The sandbox environment has test banks that you can use, and the Testing in the sandbox guide explains how to use the banks and what values to enter when asked to obtain end-user consent or payment authorization.

1. Select the GET Banks request from the Bank data folder.
2. Click Send and verify that you get a 200 OK response status.
3. Select one of the banks from the response, which is in JSON format. Note that some banks offer limited services, so you should check the list of supportedServices in the response.
4. Save the id for the bank you selected for use in subsequent requests. If you choose SEB Sweden, for example, it is c2ViLnN3ZWRlbi52MUVTU0VTRVNT.

Recipe for account requests

The steps below cover the procedure for retrieving a list of an end-user's accounts in the bank – in the case where the end-user has not yet given consent. You can see more details of this scenario on the API flow page.

Step 1: Create a session

A session maintains a context for all operations towards a bank for a particular end-user.

• bank – you selected a bank in the step above and saved its id.
• end-user – for sandbox testing purposes, the value in the header field x-device-id represents the end-user.

To create a session, complete these steps:

1. Select the POST Create session in the Session folder.
2. Select Body and replace the value of bank_id in the request body with the id you saved in the previous step. (e.g. c2ViLnN3ZWRlbi52MUVTU0VTRVNT, if you selected SEB Sweden)
3. Click Send and verify that you get a 201 Created response status. The response contains the sessionId.

The sessionId field in Variables is populated automatically, as it is needed for subsequent requests.

Step 2: Attempt to get accounts

1. Select GET Accounts in the Account information folder.
2. Click Send and verify the response status – it should be 510 Not Extended with error code 1426.

Error code 1426 shows that this GET Accounts request requires end-user consent. This will be taken care of in the next step – to see more details, look up the Consent documentation page.

Step 3: Request consent

1. Select GET Consent in the Consent folder.
2. Click Send and verify the response status – it should be 200 OK, with the response body containing a URL value in the href field. Use this URL to give consent.
3. Open the URL in an Internet browser.

Step 4: Log in to bank and give consent

The step above took you to the sandbox environment for the bank you selected previously. The procedure and credentials for consent vary between the test banks. Information about each bank is given in the Testing in sandbox guide.

As an example, if you chose SEB Sweden as your test bank, enter the value 9311219639 in the Sandbox Identity Number field and press Login. You will then get a message confirming that consent is given. It is valid for a specific period, and the /accounts endpoints can now be accessed.

Step 5: Get accounts

1. Select GET Accounts again.
2. Click Send.
3. Verify that the response status is 200 OK

The response body contains a list of the end-user's accounts.

To learn more about account requests, see the documentation pages.

Recipe for domestic payment

The steps below cover the procedure for making a domestic payment – in the case where the end-user has to authorize the payment. You can see more details of this scenario on the API flow page.

The Payments documentation pages explain the details about domestic payments as well as other payment types.

Prerequisites

• You have created a session and obtained end-user consent in the steps above.
• You need the bban numbers for a creditor and debtor account in the same currency. (Example: SEB Sweden accounts 54400047903 and 54400047881, in SEK)

Step 1: Initiate a domestic payment

1. Select POST Domestic payment in the Payments folder.
2. In the request body, replace the following fields with appropriate values:
   • \<creditor_bban>
   • \<debtor_bban>
   • \<currency_iso_code>
3. Click Send.
4. Expect response status 510 Not Extended with error code 1428. This indicates that Strong Customer Authentication (SCA) is required to authorize the payment. This is done in the next step.

Step 2: Authorize payment

1. Select GET Authorize payment in Postman.
2. Click Send.
3. Verify that the response status is 200 OK, with the response body containing a URL value in the href field. Use this URL to authorize the payment.
4. Open the URL in an Internet browser.
5. Authorize the payment according to the description for the test bank you are using. The details are explained in Testing in Sandbox. (Example: For SEB Sweden, just wait a few seconds for a confirmation message.)

Step 3: Complete payment

You authorized the payment in the previous step and can now complete it.

1. Select POST Complete payment in the Payments folder.
2. Click Send.
3. Verify that the response status is 201 Created.

The payment has now been initiated in the sandbox test bank.

Step 4: Get Payment status

Once the payment is completed you should call the Get Payment by ID endpoint at least once to confirm the payment status.

1. Select GET payment by ID in the Payments folder.
2. Click Send.
3. Verify the status.

You can continue to experiment with other payment types, just make sure the bank you choose offers the payment service you want to use.

Refreshing your access token

The access token expires after a certain period, in which case you will receive an error message (e.g. 2002 Expired token) when you try to send a request. To refresh the access token, just run Refresh token. You find it in the Authentication folder.

Modifying fields manually

The Neonomics Postman collection comes with a set of variables that get updated automatically. However, some requests contain fields that you must update manually. These fields are initially marked with angle brackets (e.g. \<field_name>). The table below explains how to modify these fields in each request.