Loan Broker API Documentation

Overview

Loan Broker API consists of four endpoints. The Loan Broker API can be used to apply for a loan, check the status of a loan application, and accept or decline loan offer. This API supports GET, POST and PUT HTTP methods. All Loan Broker API endpoint URLs contain loans.

Link to download the swagger file can be found here https://apimarket-dev02.internal.nordeaopenbanking.com/files/api-docs/premium_loan-broker-api_loan-broker-api-v1-swagger.yaml

Connecting to API

To be able to use and connect to the API there are few requirements.

• Application has to be created.
• Client ID is required.
• Client Secret is required.

To make a subscription of Loan Broker API, there is a need to login to https://developer.nordeaopenbanking.com/app/apps](https://developer.nordeaopenbanking.com/app/apps), click Create app button, and fill the form. In the “Name your app” field user can type name of the application e.g. “Loan Broker API”. In the Select team section user can select team, which will have access to the application. OAuth redirect URL should be filled by the default value - api.nordeaopenbanking.com

The Client ID and Client Secret are generated after the application is created on My apps page. The Client ID and Client Secret can be found when clicking the app icon after the app is created.

When making requests, the Client ID and Client Secret are sent in a header of each request. See the examples section of any API to learn how these headers are sent.

Note that both, Client ID and Secret are always sent, in every single request that is made towards the API

If the Client Secret is lost or leaked, it can be regenerated by clicking the reset button on the apps page.

Note that the X-IBM-Client-Id and X-IBM-Client-Secret parameters are only used by the client application. Also, the access token is made available for the client, the access token should be stored by the client application, and it should not be given to the end-user.

Migrating your application to the production environment

Whilst Nordea’s sandbox environment is provided freely to all, there is restricted access to the production environment. The sandbox environment is accessed at the following url: https://api.nordeaopenbanking.com.
You will need separate client credentials and a different url to access the production environment.

The registration process on Developer Portal is described in the Registration Guide.

To be able to use your application in the production environment with real data, the Client Application owner needs to raise a support ticket whereupon Nordea will provide more detailed information about the client onboarding process.

Differences between production and sandbox APIs

The production version of the API provides access to real application. That is, you will be able to make real request for loan and check status of the request. The Loan Broker API Sandbox is stateless application, where subscribers can just test API and pre defined responses.

API Endpoints

Like stated above, the Loan Broker API has four endpoints:

The /loans endpoint can be used to apply for a loan and it supports only POST HTTP method. When this method is used, a new loan application will be initiated. The request body must contain the loan details to be applied. This endpoint returns HTTP Code 201 on success, and the response contains the loan application details which include, e.g. decision if the application is accepted or rejected or the amount of the loan.

The /loans/{PROCESS_ENGINE_GUID} endpoint can be used to query loan application details by process engine guid, and it supports only GET HTTP method. The process engine guid is returned when loan application is initiated successfully, and it can be found from the response JSON by the name process_engine_guid. Moreover, the loan application status can be seen in the response by name detailed_status. Full response example of this endpoint can be seen on examples section below.

The /loans/{PROCESS_ENGINE_GUID}/accept endpoint can be used to accept a loan offer from Nordea. This endpoint returns HTTP Code 200 on success, and the response contains the loan application details which include, e.g. the amount of the loan.

The /loans/{PROCESS_ENGINE_GUID/reject endpoint can be used to reject a loan offer from Nordea. This endpoint returns HTTP Code 204 on success.

Loan Broker API Examples

Example: Apply for loan

This example shows how to apply for a new loan.

This endpoint URL has the following form:

POST /loans HTTP/1.1

This endpoint supports POST HTTP method.

The following cURL can be used to apply for a new loan using this endpoint.

Here is an example request:

$ curl --location -g --request POST 'https://api.nordeaopenbanking.com/non-collateral-consumer-loans/v1/loans' \
--header 'X-IBM-Client-ID: <Client ID>' \
--header 'X-IBM-Client-Secret: <Client Secret>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "loan_application": {
        "application_income_and_debt": {
            "external_debts": [],
            "house_hold_aggregate_gross_income": 900000,
            "main_applicant_income": {
                "annual_gross_income": 900000
            },
            "number_of_external_debts": 0
        },
        "extra_information_data": {},
        "loan_data": {
            "campaign_code": "50040221",
            "loan_amount": 8000,
            "loan_insurance": false,
            "loan_purpose": 10,
            "product_code": "UsikretLån",
            "repayment_period": 36
        },
        "primary_applicant_data": {
            "accomodation_information": {
                "accomodation_type": 1,
                "address_since": "1212",
                "civil_status": 1,
                "number_of_children": 0,
                "rent": 600
            },
            "email": "john.smiths@consult.nordea.com",
            "employed_since": "1212",
            "employer": "JOHN SMITHS AS",
            "firstname": "John",
            "lastname": "Smiths",
            "mobile_phone": "799999999",
            "ssn": "02065613851",
            "type_of_employment": 1
        }
    },
    "transaction_id": "123456"
}'

Here is the response for the query above:

{
    "decision": "ACC",
    "granted_amount": 8000,
    "process_engine_guid": "bf746860-8333-11eb-968a-5e61ddfafbde",
    "tenor": 36,
    "application_id": "0000000008",
    "granted_credit_limit": 0,
    "reason_codes": [
        "035",
        "646",
        "657"
    ],
    "interest": 11.27,
    "effective_interest": 12.52,
    "total_credit_limit": 0,
    "start_up_fee": 950,
    "statement_fee": 50,
    "monthly_cost": 1000,
    "loan_type": 1,
    "max_tenor": 36,
    "error": null,
    "approved_loans": null
}

The example request above is used for testing applying for a loan with status ACCEPTED. If there is a need to test applying for a loan with REJECTED status, SSN in the request body should be changed.

Also, there is a possibility to test applying for a loan with co-applicant. To do this, the request should include section with the co-applicant. Main applicant should have one of the SSN listed above - depending on status which is tested.

After the loan application is initiated by POST request to this endpoint, it will be available by doing GET request which returns a status of this loan application.

Example: Get Loan Status

This example shows how to fetch a loan application details.

This endpoint URL has the following form:

GET /loans/{PROCESS_ENGINE_GUID} HTTP/1.1

This endpoint supports GET HTTP method.

The following cURL can be used to fetch loan application details from this endpoint.

Here is an example request:

curl --location -g --request GET 'https://api.nordeaopenbanking.com/non-collateral-consumer-loans/v1/loans/bf746860-8333-11eb-968a-5e61ddfafbde' \
--header 'X-IBM-Client-ID: <Client ID>' \
--header 'X-IBM-Client-Secret: <Client Secret>' \

Here is the response for the query above:

{
    "application_id": "2726",
    "process_engine_guid": "bf746860-8333-11eb-968a-5e61ddfafbde",
    "transaction_id": null,
    "application_date": "2021-11-04T10:31:39.038",
    "payment_date": null,
    "last_updated": "2021-11-04T10:33:05.641",
    "granted_amount": 1,
    "nominal_interest_rate": 12.25,
    "effective_interest_rate": 14.81,
    "repayment_period": 36,
    "repayment_period_amount": 3416,
    "status": "PENDING",
    "detailed_status": "Wait Agent Confirmation",
    "installment_fee": 950
}

Broker API Sandbox solution gives possibility to test different statuses. To do this, path variable (GUID) in the request should be changed. Below table with GUIDs and corresponding statuses.

Example: Accept Loan Offer

This example shows how to accept a loan offer.

This endpoint URL has the following form:

PUT /loans/{PROCESS_ENGINE_GUID}/accept HTTP/1.1

This endpoint supports PUT HTTP method.

The following cURL can be used to accept a loan offer using this endpoint.

Here is an example request:

curl --location -g --request PUT 'https://api.nordeaopenbanking.com/non-collateral-consumer-loans/v1/loans/bf746860-8333-11eb-968a-5e61ddfafbde/accept' \
--header 'X-IBM-Client-ID: <Client ID>' \
--header 'X-IBM-Client-Secret: <Client Secret>' \

Here is the response for the query above:

{
    "decision": "ACC",
    "granted_amount": 12345,
    "process_engine_guid": "bf746860-8333-11eb-968a-5e61ddfafbde",
    "tenor": 30,
    "application_id": "0000000008",
    "granted_credit_limit": 0,
    "reason_codes": [
        "035",
        "646",
        "657"
    ],
    "interest": 13.45,
    "effective_interest": 15.2,
    "total_credit_limit": 0,
    "start_up_fee": 950,
    "statement_fee": 50,
    "monthly_cost": 1000,
    "loan_type": 1,
    "max_tenor": 36,
    "error": null,
    "approved_loans": null
}

Example: Reject Loan Offer

This example shows how to reject a loan offer.

This endpoint URL has the following form:

PUT /loans/{PROCESS_ENGINE_GUID}/reject HTTP/1.1

This endpoint supports PUT HTTP method.

The following cURL can be used to reject a loan offer using this endpoint.

Here is an example request:

curl --location --request PUT 'https://api.nordeaopenbanking.com/non-collateral-consumer-loans/v1/loans/2a5215b7-77ee-425a-94b6-e7293d6c77be/reject' \
--header 'X-IBM-Client-ID: <Client ID>' \
--header 'X-IBM-Client-Secret: <Client Secret>' \

This endpoint does not return any response body. In response, we only receive HTTP Code 204.

Common issues

In this section, we describe some of the common issues that the users of the API face. This section is updated periodically.

Client secret is lost

If you lose the client secret, you must generate a new one in the developer portal.

Application ID is not registered

If you receive this error when making a request, please double-check in the developer portal that you are subscribed to the APIs you wish to use.

API returns 500 and not a meaningful error message

In this case, most commonly, the request or request payload is invalid. Please check the request you are making carefully.

Postman collection is not working properly

First, please check that the client secret and client id is set properly.

Next, ensure that Automatically follow redirects is disabled in Postman, for this to work, you need to have the interceptor extension installed and activated for Postman. See capturing http requests and issues/2722.

Getting started with the API using Postman

In this section, we take a look how to get started with the API by using Postman. If you are new to Postman, see the documentation and tutorials.

First, save the collection for Postman from here.

and import it to the postman. Next, you have to create an environment which has X-IBM-Client-ID and X-IBM-Client-Secret variables, i.e., your application id and application secret. You can find the correct values for those from the app console in developer portal.

Next, make sure that you disable Automatically follow redirects from the Postman settings. For instructions how to do this, see this.

After these steps, you can run the collection.