Development & test

The integration between DIC and SP/FI consists of pushing data and pulling data. Make sure you are well familiar with Standards Specification v1.2.0 and Security Document v1.3.0

• PULL - DIC pulls data from SP/FI through REST API at SP/FI
• PUSH - SP/FI push updates to API at DIC

Below the API for pull and push are described and defined. Further, examples of use.

• API - PULL - Financial institutions (FI)

• API - PUSH - Debt information company

• Examples DIC pull information
• Examples FI push changes

• Example configuration of FI & service providers (SP)

• OpenAPI documentation - test API

URL

The URL for each service will be based on the following format: https://host:port/serviceName/version/path

• The serviceName is defined as: debt-information
• The version is defined as: v1
• The path is defined for each of the services below.

A portal may provide different addresses for push of all data versus updates.

API - Financial institutions

The table below lists the services for this interface. UTF-8 shall be used as a charset and “application/json” shall be supported as content type.

Method	Path	Description
GET	/loans/	Get debt information for all FIs from a service provider (SP)
GET	/loans/{financialinstitutionid}	Get debt information for all customers for one FI

Get information about all customers (/loans/)

Get all debt information from the Service provider. Pre-processed files could be created in advance based on file size. In cases where FI/SP is required to use paging functionality, the number of pages shall be returned as a header parameter in the response from service provider.

Get information about all customers (/loans/{financialinstitutionid}) for a financial institution

Get all debt information for a single FI. A pre-processed file or real-time generated data should be returned. In cases where FI is required to use paging functionality, the number of pages shall be returned as a header parameter in the response from FI.

Path and query parameters:

Parameter	Description
	None parameter, indicates that the service will returns all data from the FI/SP
financialinstitutionid	Optional path parameter to identify the FI the query is targeted at. Multiple FIs may be included in the response, if financialinstitutionid is not included in the request. Example: /loans/999777888
page	Query parameter used to specify the page request, if FI/SP is required to use paging functionality (FUNC-06). Optional parameter, default value is 0. Pages are numbered from 0. Example: If numberOfPages are 10, they are numbered as [0..9]

Response Headers:

Response Header	Description
numberOfPages	Defines the number of pages that can be fetched from the FI. Used in the http response only. If not specified the number of pages is one page.
page	Defines the number of pages that can be fetched from the FI. Used in the http response only. If not specified the number of pages is one page.

Response codes:

Code	Description
200	Default response code
400	Invalid input data
401	Authentication is missing or not correct
403	Not allowed to access resource
429	Too many requests

API - Debt information companies

The table below defines the services that the DIC must provide to the FIs. UTF-8 shall be used as a charset and “application/json” shall be supported as content type.

Path and query parameters:

Method	Path	Description
POST	/loans	Post notification about changes in a customer’s debt information

Request body

Defined in the Standards Specification v1.2.0

Response body

Defined in the Standards Specification v1.2.0

Response codes:

Code	Description
200	Default response code
400	Invalid input data
401	Authentication is missing or not correct
403	Not allowed to access resource
429	Too many requests

API - Examples - DIC pull information

DIC fetches information about all customers from one FI/SP

Description:
DIC fetches information about all customers for one FI by calling service /loans/{financialinstitutionid} at FI/SP.

Pre-condition:
FI/SP Onboarding has prepared a data set that is ready each night or real-time generated data.

Procedure:
DIC sends request to FI/SP, FI/SP responds with data.

Error procedure:

• DIC resends request, if request times out.

Post-condition:
DIC have information about all customers

Example

Request

GET /loans/123456789

Accept: application/json
Accept-Encoding: deflate

Response

200 OK

Content-Type: application/json
Encoding: deflate

{
	"providerID" : "9908:999888777",
	"customers" : [{
		<<<Data about all customer>>>
		}]
	}]
}

Example with paging

Request

GET /loans/123456789?page=0

Accept: application/json
Accept-Encoding: deflate

Response

200 OK

Content-Type: application/json
Encoding: deflate
numberOfPages: 1

{
	"providerID" : "9908:999888777",
	"customers" : [{
		***<<<Data about all customer>>>***
		}]
	}]
}

DIC fetches information about all FIs and associated customers

Description:
DIC fetches data about all FIs from a SP or the FI provides its own data. In this context the FI will be handled with the same premises as an SP. By calling service /loans/ at FI/SP.

Pre-condition:
SP has prepared a data set that contains data for all FIs they provide each night.

Procedure:
DIC sends request to FI/SP, FI/SP responds with data.

Error procedure:

• DIC resends request, if request times out.

Post-condition:
DIC have information about all FIs and associated customers.

Example - with paging

Request

GET /loans/?page=0

Accept: application/json
Accept-Encoding: deflate

Response

200 OK

Content-Type: application/json
Encoding: deflate
numberOfPages: 1

{
	"providerID" : "9908:999888777",
	"customers" : [
	    {
            "customerID" : "32021112345",
            "financialInstitutionID" : "998877665",
            "loans" : []
		},
        {
            "customerID" : "32021112345",
            "financialInstitutionID" : "999555221",
            "loans" : []
		},
        {
            "customerID" : "38157022556",
            "financialInstitutionID" : "998554221",
            "loans" : []
		}

		<<<Data for more FIs and customers>>>
    ]
}

API - Examples - FI push changes

FI/SP: Loan/credit is new or changed

Description:
A new loan/credit and changes to an existing loan/credit shall be reported by the FI/SP to DIC in near real-time. The uses case includes reporting of new credit when FI/SP gets new customer.

Pre-condition:
A new loan or credit limit has been granted by a FI/SP to a customer.

Procedure:
The loan is reported from the FI/SP to DIC

Error procedure:

• If request times out or success response is not received: FI/SP resends request each ten minutes until response is received or until a complete dataset is created and fetched by the DIC (as in fetches examples above).

Post-condition:
DIC is informed that a credit limits was changed, a customer got a new credit, or that a new customer was granted credit or loan.

Example

Request

POST /loans

Content-Type: application/json

{
	"providerID" : "9908:123456789",	
	"customers" : [
		{
		"customerID" : "32021112345",
		"financialInstitutionID" : "123456789",
		"loans" : [{
			"type" : "creditFacility",
			"timestamp" : "2018-04-09T10:13:12Z",
			"accountID" : "4001",
			"accountName" : "Kort",
			"creditLimit" : "10000000",
			"interestBearingBalance" : "0",
			"nonInterestBearingBalance" : "0",
			"nominalInterestRate" : "0800",
			"installmentCharges" : "0",
			"installmentChargePeriod" : "MONTHLY",
			"coBorrower" : "0"
			}]
		},
		{
		"customerID" : "32057563214",
		"financialInstitutionID" : "987654321",
		"loans" : [{
			"type" : "chargeCard", 
			"timestamp" : "2018-04-09T10:13:16Z",
			"accountID" : "52",
			"accountName" : "Kort",
			"interestBearingBalance" : "0",
			"nonInterestBearingBalance" : "12500",
			"coBorrower" : "0"
			}]
		}]
}

Response

200 OK

Content-Type: application/json

{
	"timestamp" : "2018-04-09T10:13:12Z",
"uuid" : "e180341c-13e5-4a42-a835-0ef4be5320fc"
}

FI/SP: Loan or credit is repaid

Description:
This use cases is related to reporting of a loan that has been repaid, shall be reported by the FI/SP to DIC in near real-time

Pre-condition:
A previously reported loan or credit is repaid.

Procedure:
The loan is reported to the DICs with a credit limit/balance set to zero.

Error procedure:

• If request times out or success response is not received: FI/SP resends request each ten minutes until response is received or until a complete dataset is created and sent to DIC.

Post-condition:
DICs have received information about repaid loan or credit.

Example

Request

POST /loans

Content-Type: application/json

{
	"providerID" : "9908:123456789",
	"customers" : [{
		"customerID" : "32021112345",
		"financialInstitutionID" : "123456789",
		"loans" : [
		{
			"type" : "creditFacility",
			"timestamp" : "2018-04-09T10:15:52Z",
			"accountID" : "4001",
			"accountName" : "Kort",
			"creditLimit" : "0",
			"interestBearingBalance" : "0",
			"nonInterestBearingBalance" : "0",
			"nominalInterestRate" : "0",
			"installmentCharges" : "0",
			"installmentChargePeriod" : "MONTHLY",
			"coBorrower" : "0"
		},
		{
			"type" : "chargeCard", 
			"timestamp" : "2018-02-05T12:54:11Z",
			"accountID" : "52",
			"accountName" : "Kort",
			"interestBearingBalance" : "0",
			"nonInterestBearingBalance" : "0",
			"coBorrower" : "0"		
		},
		{
			"type" : "repaymentLoan",
			"timestamp" : "2018-02-05T12:59:32Z",
			"accountID" : "31",
			"accountName" : "Forbrukslån 100%",
			"originalBalance" : "0",
			"balance" : "0",
            "terms" : "0",
			"nominalInterestRate" : "0",
			"installmentCharges" : "0",
            "installmentChargePeriod" : "MONTHLY",
			"coBorrower" : "0"
		}]
	}]
}

Response

200 OK

Content-Type: application/json

{
	"timestamp" : "2018-04-09T10:15:52Z",
    "uuid" : "986cbe27-1f00-45c6-8baf-c6de97dffdbf"
}

FI/SP: Balance or interest is changed

Description:
The balance or interest has been changed for a loan or credit.

Pre-condition:
FI/SP has previously reported data about the customer.

Procedure:
Data is reported in the next complete data set that will be available latest during the next night.

Error procedure:

• N/A

Post-condition:
Updated balance or interest is included in the next complete data set.