# Accounts and Transactions source: https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/tutorials/accounts-transactions-tutorial/index.md This tutorial guides you through the process of connecting to a user's account, reading their accounts info and transactions details. #### Prerequisites: {#prerequisites} * You must have created an App. Make sure you have recorded the `CLIENT_ID` and `CLIENT_SECRET`. * This tutorial uses `curl` in order to send requests and receive responses. ### Step 1 - User Authentication {#step-1---user-authentication} Create a supervised login request and retrieve an `authUrl` for the user to login to their bank. API Reference: `POST /v1/authentication/initialize` #### Request {#request} * Create a `USER_HASH` to identify the user. * Specify a `REDIRECT_URL` where the user will be redirected after finishing the supervised login flow. ```shell curl -X POST \ https://api.nordicapigateway.com/v1/authentication/initialize \ -H 'Content-Type: application/json' \ -H 'X-Client-Id: ' \ -H 'X-Client-Secret: ' \ -d '{ "userHash": "", "redirectUrl": "" }' ``` #### Response {#response} If the request is successful, the response will look like: ```json { "authUrl": "https://api.nordicapigateway.com/v1/authentication/start?startToken=ugAAAAVDaXBoZXJ0ZXh0AIAAAAAAqG8X41PoyO1Um4GsHQlqmy7c02mhontKuu2VrUBIqYzJU%2BfJ%2FuZWKmYvrBhXnpVnSDLWJsBsam9dvRCFax1Rm5KE%2FTPBTWA4oa3PtNaUWknlgGzzdFRdRss0kCE1aSCelG7lrZnN%2FXenBXRSMtTWmFfj%2FFQ2TpGgYdwznZ2uPLIFSXYAEAAAAAC1XEnqjqmz2l%2Bo0axEk7WgEEtleUlkAAAAAAAA", "sessionId": "20190824.xrrksqlmngnw3xisfq8uqd1ijh>" } ``` * Record the `sessionId` for next steps. * Redirect the user to the `authUrl` to start the supervised login flow. ### Step 2 - Supervised Login Flow​ {#step-2---supervised-login-flow} Redirect the user to the `authUrl` received in the previous step for them to login to their bank. Note: The Auth URL must not be presented in an iframe, and it cannot be reused. Depending on the parameters passed in the request, a flow will be displayed to the user where they will be able to select their provider (if not specified) and login. The flow will look like: ![Login flow](https://static.developer.mastercard.com/content/open-finance-europe/uploads/login-flow.png) ### Step 3 - Obtain Authentication Code {#step-3---obtain-authentication-code} After the supervised login flow is completed, the PSU is redirected back to the application using the `redirectUrl`. The redirection will look like: https://example.org/demo/redirect?code=qgAAAAVDaXBoZXJ0ZXh0AHAAAAAAhc3pqKXxpxfZnLBlBK8FZApw9cEVp7Fp9d0tcRGsx7Q9/t0gmKcPuh0jsny/VjT4Y7WTXZLPvmFjuCYUyKWgFeZs3iFVygNXZrtwHIocNFbRYSVHcIalV3Oleyc9JV4XcD4o/p++gDBWKRsSzipqQwVJdgAQAAAAABSXV44SuwfpjExvUiTg6IsQS2V5SWQAAAAAAAA= If the login was successful, the `redirectUrl` query will hold the `code` for use in the next step. Otherwise, the user will be redirected to the `redirectUrl` and the query will contain a `success` parameter with a value of `false` and an `error` parameter with the error reason. ### Alternative method for retrieving the code and checking the session state {#alternative-method-for-retrieving-the-code-and-checking-the-session-state} Alternatively, you can create a request to check the session status. API Reference: `GET /v1/authentication/{sessionId}/status` #### Request {#request-1} * Use the `SESSION_ID` retrieved when starting the supervised login in the first step. ```shell curl -X GET \ https://api.nordicapigateway.com/v1/authentication//status \ -H 'Content-Type: application/json' \ -H 'X-Client-Id: ' \ -H 'X-Client-Secret: ' ``` #### Response {#response-1} If the request is successful, the response will look like: ```json { "state": "Succeeded", "code": "qgAAAAVDaXBoZXJ0ZXh0AHAAAAAAhc3pqKXxpxfZnLBlBK8FZApw9cEVp7Fp9d0tcRGsx7Q9/t0gmKcPuh0jsny/VjT4Y7WTXZLPvmFjuCYUyKWgFeZs3iFVygNXZrtwHIocNFbRYSVHcIalV3Oleyc9JV4XcD4o/p++gDBWKRsSzipqQwVJdgAQAAAAABSXV44SuwfpjExvUiTg6IsQS2V5SWQAAAAAAAA=" } ``` Ensure the `state` is `Succeeded` and obtain the `code` for use in the next step. ### Step 4 - Exchange Code for Token {#step-4---exchange-code-for-token} The `code` retrieved from the previous step will be exchanged for an `accessToken` for use to retrieve accounts and transactions. API Reference: `POST /v1/authentication/tokens` #### Request {#request-2} * Use the `CODE` retrieved from the previous step to get the access token. ```shell curl -X POST https://api.nordicapigateway.com/v1/authentication/tokens \ -H 'X-Client-Id: ' \ -H 'X-Client-Secret: ' \ -d '{ "code": "" }' ``` #### Response {#response-2} If the request is successful, the response will look like: ```json { "session": { "expires": "2022-09-06T14:00:00.000+00:00", "accessToken": "", "scopes": [ "Accounts", "UnattendedLogin" ] }, "login": { "providerId": "DemoBank", "expires": "2023-03-08T14:00:00.000+00:00", "loginToken": "", "supportsUnattended": true, "label": "DemoBank, user 12345, created 9/6/2022 2:00:00 PM", "subjectId": "", "aisScaExpires": "2022-12-05T14:00:00.000+00:00" }, "providerId": "DemoBank" } ``` * Record the `accessToken` for next steps. * You can use the `loginToken` for unattended logins. ### Step 5 - Accounts Retrieval {#step-5---accounts-retrieval} Use the `accessToken` retrieved from the previous step to read the user accounts. API Reference: `GET /v2/accounts` #### Request {#request-3} * Use the `ACCESS_TOKEN` retrieved from the previous step to get the user accounts. ```shell curl -X GET https://api.nordicapigateway.com/v2/accounts \ -H 'X-Client-Id: ' \ -H 'X-Client-Secret: ' \ -H 'Authorization: Bearer ' ``` #### Response {#response-3} If the request is successful, the response will look like: ```json { "accounts": [ { "id": "5d5bcLTPv-HH-pV26cT67lrIY8kwz59whYjEJasHyUc.5ef85601bc3b", "idSchema": "T1-20170101", "providerId": "DemoBank", "name": "Checking Account", "owner": "John Doe", "addressUnstructured": "Street Name 123", "accountUsage": "Business", "psuRole": "Account Holder", "bookedBalanceDate": "2023-01-01T00:00:00", "availableBalanceDate": "2023-01-01T00:00:00", "number": { "bbanType": "DK", "bban": "0400-3302021", "iban": "DK12000403302021", "card": { "maskedPan": "4512********1234", "cardHolder": "John Doe", "expireYear": 2030, "expireMonth": 12 }, "bbanParsed": { "bankCode": "0400", "accountNumber": "3302021" } }, "bookedBalance": { "value": 100, "currency": "DKK" }, "availableBalance": { "value": 100, "currency": "DKK" }, "type": "Consumption", "features": { "queryable": true, "psdPaymentAccount": true, "paymentFrom": true, "paymentTo": true }, "topUpInformation": { "destination": { "bban": { "bankCode": "string", "accountNumber": "string" }, "iban": { "ibanNumber": "string" }, "ownAccount": { "accountId": "string" }, "name": "John Doe" }, "message": "Some message", "identifiers": { "creditorReference": "string", "endToEndId": "string", "finnishReference": "string", "norwegianKid": "string", "ocr": "string", "estonianReference": "string" } }, "pendingAmount": { "value": 100, "currency": "DKK" }, "creditLimit": { "value": 100, "currency": "DKK" } } ], "pagingToken": "iQEAAAVDaXBoZXJ0ZXh0ADkBAAAA0euJxDW5HdQl0U3_TZ3Knem0MWDjn0B9jEiMxgMsPIzaWW2tv86fzieeZqB0Tdr76MurtldQhKCs86WUklZhboxqrZ3RFPrKv9t6hg3uKfae9w8bO7Y32LmJhPUTFpaMqhmZZvCbO" } ``` * Record the `id` to retrieve the transactions. ### Step 6 - Transactions Retrieval {#step-6---transactions-retrieval} Use the `accessToken` and `accountId` retrieved from the previous step to read the account transactions. API Reference: `GET /v2/accounts/{accountId}/transactions` #### Request {#request-4} * Use the `ACCESS_TOKEN` and `ACCOUNT_ID` retrieved from the previous step to get the user accounts. ```shell curl -X GET https://api.nordicapigateway.com/v2/accounts//transactions \ -H 'X-Client-Id: ' \ -H 'X-Client-Secret: ' \ -H 'Authorization: Bearer ' ``` #### Response {#response-4} If the request is successful, the response will look like: ```json { "transactions": [ { "id": "ac1e5d2bb25aa2484a3f7e87c92c2685", "idSchema": "T1-20170101", "date": "2022-01-01", "creationTime": "2022-01-01", "text": "Pastry shop", "originalText": "Pastry shop", "details": { "message": "Payment for cinnamon rolls", "valueDate": "2022-01-01", "executionDate": "2022-01-01", "reward": { "type": "Cashback", "amount": { "value": 100, "currency": "DKK" }, "points": 0 }, "source": { "account": { "bbanType": "DK", "bban": "0400-3302021", "iban": "DK12000403302021", "card": { "maskedPan": "4512********1234", "cardHolder": "John Doe", "expireYear": 2030, "expireMonth": 12 }, "bbanParsed": { "bankCode": "0400", "accountNumber": "3302021" } }, "name": "John Doe's Grocery Shop", "address": "Rådhuspladsen 1234\n1550 København", "merchantCategoryCode": "5411", "merchantCategoryName": "Grocery Stores, Supermarkets" }, "destination": { "account": { "bbanType": "DK", "bban": "0400-3302021", "iban": "DK12000403302021", "card": { "maskedPan": "4512********1234", "cardHolder": "John Doe", "expireYear": 2030, "expireMonth": 12 }, "bbanParsed": { "bankCode": "0400", "accountNumber": "3302021" } }, "name": "John Doe's Grocery Shop", "address": "Rådhuspladsen 1234\n1550 København", "merchantCategoryCode": "5411", "merchantCategoryName": "Grocery Stores, Supermarkets" }, "identifiers": { "reference": "123456789", "document": "123456789", "sequenceNumber": "0000012345", "terminal": "1234567", "creditorReference": "RF18 5390 0754 7034", "endToEndId": "B2HGCDTE34PXRU4F6K7EY6TN2VWMX9BJS1C", "finnishReference": "00000000000001234561", "finnishArchiveId": "57509530547841", "norwegianKid": "123456701123453" }, "routing": [ "Service Provider 1", "Service Provider 2" ], "currencyConversion": { "originalAmount": { "value": 100, "currency": "DKK" }, "exchangeRate": 7.4377093 } }, "category": { "id": "14", "setId": "14" }, "amount": { "value": 100, "currency": "DKK" }, "balance": { "value": 100, "currency": "DKK" }, "type": "Card", "state": "Booked" } ], "pagingToken": "iQEAAAVDaXBoZXJ0ZXh0ADkBAAAA0euJxDW5HdQl0U3_TZ3Knem0MWDjn0B9jEiMxgMsPIzaWW2tv86fzieeZqB0Tdr76MurtldQhKCs86WUklZhboxqrZ3RFPrKv9t6hg3uKfae9w8bO7Y32LmJhPUTFpaMqhmZZvCbO", "ordering": "ReverseChronological" } ```