API Market

Premium APIsCompliance APIs
Premium APIsRetail FinanceCredit Application API v2

Credit Application

Application with Purchase

Overview

The Application with Purchase API is the single way to apply for credit and make purchase.

Apply for Credit information needs to be provided in credit applicant format. Described in swagger definition. In credit applicant information such as national person id, name, address, phone number, email address etc. is to be provided by user, along with proficient details such as occupation type, industry, gross income, loan type etc. In the Purchase section, details of purchase item details such as purchase item, amount, id, mode of purchase, campaign details etc to be provided by TPP. The behaviour of the API will varies in sandbox as compared to actual production environment.

Changes from the previous version

This is the changelog of Application with Purchase API. The topmost item is the latest version and the changes described in it are relative to the previous version which is listed directly below. The current version of the API documentation is 2.0

Sample flow

Below you can find a sample flow diagram

diag

Swagger Definition

The API specification is also available in the swagger format.

Application with Purchase – This will updated by OBD ( Open banking Department)

Request Header Parameter

Sr.No.Field NameTypeMandatory InformationExample
1x-ibm-client-idStringMandatoryyou will get it from developer portal.
2x-ibm-client-secretStringMandatoryyou will get it from developer portal.
3api-keyStringMandatoryNeed to generate every time - c9483211-e8ed-490b-8238-bf2fc5823ca2

Request URL parameters: TBD

Request Body: User need to add body while posting the request . The request will be in Json format and the parameters details are as below.

Sr.No.Field NameTypeMandatoryExamples
1country_idStringYFI
2channelStringYW
3dealer_idStringYDK0001
4product_codeStringY20
5user_idStringY210281-9988,210281-9912,110788-1133
6is_new_applicationBooleanYtrue, false
7purchase_details. order_reference_idStringN-
8purchase_details.purchase_items. item_idintY10
9purchase_details.purchase_items. item_nameStringYTV
10purchase_details.purchase_items.item_amount amount_partdecimalY100
11purchase_details.purchase_items.item_amount currency_codeStringYEUR
12purchase_details.purchase_item. purchase_estimated_delivery_dateDateY2022-11-16
13purchase_details. total_purchase_amount. amount_partdecimalY100
14purchase_details. total_purchase_amount. currency_codeStringYEUR
15applicant_details.applicant_personal_details.national_person_idStringY110487-1708
16applicant_details.applicant_personal_details.pep_informationbooleanNtrue, false
17applicant_details.applicant_personal_details.california_citizenshipbooleanNtrue, false
18applicant_details.applicant_personal_details.first_nameStringYJohan
19applicant_details.applicant_personal_details.surnameStringYPaul
20applicant_details.applicant_personal_details.language_codeStringYS / FI / da-dk
21applicant_details.applicant_personal_details.individual_marital_statusString Y
22applicant_details.applicant_personal_details.taxation_countryStringYFI
23applicant_details.applicant_personal_details.nationalityStringYFI
24applicant_details.applicant_personal_details.addressStringYAnnankatu 1
25applicant_details.applicant_personal_details.cityStringYEspoo
26applicant_details.applicant_personal_details.postal_codeStringY00100
27applicant_details.applicant_personal_details.residence_ownership_styleStringY30
28applicant_details.applicant_personal_details.phone_country_codeStringY123
29applicant_details.applicant_personal_details.phone_domestic_numberStringY123456
30applicant_details.applicant_personal_details.EmailStringYjohoan@gmail.com
31applicant_details.applicant_personal_details.Card_in_useStringYVISA
32applicant_details.applicant_proficient_details.Occupation_groupStringY11
33applicant_details.applicant_proficient_details.employment_typeStringY
34applicant_details.applicant_proficient_details.Employer_industryStringY
35applicant_details.applicant_proficient_details.Starting_month_of_employmentintY6
36applicant_details.applicant_proficient_details.Starting_year_of_employmentintY2021
37applicant_details.applicant_proficient_details.loan_type.loanStringYHome
38applicant_details.applicant_proficient_details.loan_type.credit_debt_amountdecimalY1000
39credit_information.term_amount.amount_partdecimalY1000
40credit_information.term_amount. currency_codeStringYEUR
41credit_information.Due_dateintY3
42credit_information.monthly_feedecimalY10
43credit_information.base_rateString
44credit_information.loan_marginDecimalY10.2
45credit_information.euribor_rateStringY-0.5
46credit_information.loan_amount_totaldecimalY10000
47credit_information.annual_interest_rateDecimalY11.11
48credit_information.monthly_paymentDecimalY1234
49credit_information.no_of_monthly_paymnetsIntY12
50supporting_details.opening_feeDecimalY123
51supporting_details.repayment_rateDecimalY12.34
52supporting_details.other_feeDecimalY12.12
53campaign_details.camp_typeIntY1
54campaign_details.camp_productIntY1
55campaign_details.camp_nameStringY12
56campaign_details.camp_codeStringY12
57campaign_details.camp_lengthIntY12
58campaign_details.camp_who_pays_acc_feeIntY
59campaign_details.camp_customer_pays_provisionIntY
60campaign_details.camp_vendor_is_payd_feeintY
61campaign_details.camp_purchase_typeintY
62campaign_details.camp_no_of_installmentsintY
63campaign_details.camp_customer_pays_provision_moneyintY
64campaign_details.camp_customer_pays_provision_moneyintY

Response Body

Sr.No.Field NameTypeExample
1application_response. statusdoubleAPPROVED/REJECTED/CANCELLED
2application_response. credit_application_idString12345
3purchase_response. is_order_confirmedbooleantrue/false
4purchase_response. order_reference_idStringNull/ORDER3349891625
5purchase_response.purchase_items.purchase_item.item_idint1
6purchase_response.purchase_items.purchase_item.item_nameStringTV
7purchase_response.purchase_items.purchase_item.item_amount.amount_partdecimal1000
8purchase_response.purchase_items.purchase_item.item_amount.currency_codeStringEUR
9purchase_response.purchase_items.purchase_item.purchase_estimated_delivery_dateString2019-09-19

Examples

Request Body

{
  "country_id":"FI",
  "channel":"S",
  "dealer_id":"123456789",
  "product_code":"20",
  "user_id":"010299-123E",
  "is_new_application":true,
  "purchase_details":{
    "order_reference_id":"ORDER1234569",
    "purchase_items":{
      "purchase_item":[
        {
          "item_id":100,
          "item_name":"Sofa",
          "item_amount":{
            "amount_part":90,
            "currency_code":"EUR"
          },
          "purchase_estimated_delivery_date":"2021-11-25"
        }
      ]
    },
    "total_purchase_amount":{
      "amount_part":90,
      "currency_code":"EUR"
    }
  },
  "applicant_details":{
    "applicant_personal_details":{
      "national_person_id":"123456-XXXX",
      "pep_information":false,
      "california_citizenship":false,
      "first_name":"testi",
      "surname":"kamp kaksi d",
      "language_code":"S",
      "individual_marital_status":"10",
      "taxation_country":"FI",
      "nationality":"FI",
      "address":"testikatu 12345",
      "city":"helsinki",
      "postal_code":"00500",
      "residence_ownership_type":"10",
      "phone_country_code":"358",
      "phone_domestic_number":"401234567",
      "email":"testperson@testdomain.com",
      "cards_in_use":"DEBIT,VISA"
    },
    "applicant_proficient_details":{
      "occupation_group":"31",
      "employment_type":"10",
      "employer_industry":"12",
      "starting_month_of_employment":"10",
      "starting_year_of_employment":"2000",
      "gross_income_total":{
        "amount_part":5000,
        "currency_code":"EUR"
      },
      "loan_type":[
        {
          "loan":"Home",
          "credit_debt_amount":0
        },
        {
          "loan":"Other",
          "credit_debt_amount":0
        }
      ]
    }
  },
  "credit_information":{
    "term_amount":{
      "amount_part":1200,
      "currency_code":"EUR"
    },
    "due_date":1,
    "monthly_fee":3.5,
    "base_rate":"-0.478",
    "loan_margin":8,
    "euribor_rate":"-0.325",
    "loan_amount_total":2000,
    "annual_interest_rate":13.5,
    "monthly_payment":40,
    "no_of_monthly_payments":11
  },
  "supporting_details":{
    "opening_fee":0,
    "repayment_rate":10,
    "other_fees":0
  },
  "campaign_details":{
    "camp_type":"0",
    "camp_product":"568",
    "camp_name":"2D Joustorahoitus lyhennysprosentti 10% Kuluton Tasaer 20kk uudet ja jatko-ostot",
    "camp_code":"8009",
    "camp_length":20,
    "camp_who_pays_acc_fee":"2",
    "camp_customer_pays_provision":"1",
    "camp_vendor_is_payd_fee":"0",
    "camp_purchase_type":2,
    "camp_no_of_installments":"20",
    "camp_customer_pays_provision_money":0.1,
    "camp_customer_pays_provision_money":"1"
  }
}

Success Response

{
    "application_response": {
        "status": "APPROVED",
        "credit_application_id": "44996ef4-ca6d-4446-b497-6bfaa8544c8d"
    },
    "purchase_response": {
        "is_order_confirmed": true,
        "order_reference_id": "ORDER1234569",
        "purchase_items": {
            "purchase_item": [
                {
                    "item_id": "100",
                    "item_name": "Sofa",
                    "item_amount": {
                        "amount_part": 90,
                        "currency_code": "EUR"
                    },
                    "purchase_estimated_delivery_date": "2021-11-25"
                }
            ]
        }
    }
}

Error Responses

Scenario - double submission of same request

HTTP/1.1 400

{
    "application_response": {
        "status": "CANCELLED",
        "credit_application_id": "2ff013a9-be6f-4ee3-b8c3-36f974cdc469"
    },
    "purchase_response": {
        "is_order_confirmed": false
    }
}

Scenario : for wrong input data ( sample ) HTTP/1.1 400

{
    "errorId": "CFAP-400",
    "category": "APPLICATION",
    "message": "Bad Request - WRONG Country Id",
    "timestamp": "2021-02-23T06:45:44.083+0000"
}

Purchase with Credit

Overview

The Purchase API is the way to purchase new items for any customer.

In Purchase API only existing customer can buy the new item. There is possibility to buy multiple items at one time.

Some details of purchase item details such as purchase item, amount , id, mode of purchase , campaign details etc are present. Customer details and partner details also required for this process.

Changes from the previous version

This is the changelog of Purchase with Credit API. The topmost item is the latest version and the changes described in it are relative to the previous version which is listed directly below. The current version of the API documentation is 2.0.

Sample flow

Below you can see the sample flow.

diag

Swagger Definition

The API specification is also available in the swagger format

Purchase with Credit - This will updated by OBD ( Open banking Department)

Request Header Parameter

Sr.No.Field NameTypeMandatory InformationExample
1x-ibm-client-idStringMandatoryyou will get it from developer portal.
2x-ibm-client-secretStringMandatoryyou will get it from developer portal.
3api-keyStringMandatoryNeed to generate every time - c9483211-e8ed-490b-8238-bf2fc5823ca2

Request Body parametrs

User need to add body while posting the request. The request will be in Json format and the parameters details are as below

Sr.No.Field NameTypeMandatoryExamples
1country_idStringYFI
2channelStringYS
3partner_dealer_idStringYDK0001
4national_person_idString
5card_numberString
6purchase_details.order_reference_id
7purchase_details.purchase_items. item_idintY10
8purchase_details.purchase_items. item_nameStringYTV
9purchase_details.purchase_items.item_amount amount_partdecimalY100
10purchase_details.purchase_items.item_amount currency_codeStringYEUR
11purchase_details.purchase_item. purchase_estimated_delivery_dateDateY2022-11-16
12purchase_details. total_purchase_amount. amount_partdecimalY100
13purchase_details. total_purchase_amount. currency_codeStringYEUR
14campaign_details.camp_typeIntY1
15campaign_details.camp_productIntY1
16campaign_details.camp_nameStringY12
17campaign_details.camp_codeStringY12
18campaign_details.camp_lengthIntY12
19campaign_details.camp_who_pays_acc_feeIntY
20campaign_details.camp_customer_pays_provisionIntY
21campaign_details.camp_vendor_is_payd_feeintY
22campaign_details.camp_purchase_typeintY
23campaign_details.camp_no_of_installmentsintY
24campaign_details.camp_customer_pays_provision_moneyintY
25campaign_details.camp_customer_pays_provision_moneyintY

Response Body

Sr.No.Field NameTypeExample
1application_response. statusdoubleAPPROVED/REJECTED/CANCELLED
2application_response. credit_application_idString12345
3purchase_response. is_order_confirmedbooleantrue/false
4purchase_response. order_reference_idStringNull/ORDER3349891625
5purchase_response.purchase_items.purchase_item.item_idint1
6purchase_response.purchase_items.purchase_item.item_nameStringTV
7purchase_response.purchase_items.purchase_item.item_amount.amount_partdecimal1000
8purchase_response.purchase_items.purchase_item.item_amount.currency_codeStringEUR
9purchase_response.purchase_items.purchase_item.purchase_estimated_delivery_dateString2019-09-19

Examples

Request Body

{
    "country_id": "FI",
    "channel": "S",
    "partner_dealer_id": "123456789",
    "national_person_id": "220220-YYYY",
    "card_number": "YWNjb3VudE51bWJlcg==",
    "purchase_details": {
        "order_reference_id": "123456789123",
        "purchase_items": {
            "purchase_item": [{
                    "item_id": 100,
                    "item_name": "Table",
                    "item_amount": {
                        "amount_part": 5,
                        "currency_code": "EUR"
                    },
           "purchase_estimated_delivery_date": "2021-12-25"
                },
                {
                    "item_id": 101,
                    "item_name": "Chair",
                    "item_amount": {
                        "amount_part": 1,
                        "currency_code": "EUR"
                    },
           "purchase_estimated_delivery_date": "2021-12-25"
                }
            ]
        },
        "total_purchase_amount": {
            "amount_part": 6,
            "currency_code": "EUR"
        }
    },
    "campaign_details": {
        "camp_type": "1",
        "camp_product": "123",
        "camp_name": "2D Joustorahoitus lyhennysprosentti 10% Kuluton Tasae 20kk uudet ja jatko-ostot",
        "camp_code": "8009",
        "camp_length": 20,
        "camp_who_pays_acc_fee": "1",
        "camp_customer_pays_provision": "1",
        "camp_vendor_is_paid_fee": "0",
        "camp_purchase_type": 2,
        "camp_no_of_installments": "1",
        "camp_customer_pays_provision_money": 0.1,
        "camp_customer_pays_provision_percent": "1 "
    }
}

Success Response

{
    "application_response": {
        "status": "APPROVED",
        "credit_application_id": "44996ef4-ca6d-4446-b497-6bfaa8544c8d"
    },
    "purchase_response": {
        "is_order_confirmed": true,
        "order_reference_id": "ORDER1234569",
        "purchase_items": {
            "purchase_item": [
                {
                    "item_id": "100",
                    "item_name": "Sofa",
                    "item_amount": {
                        "amount_part": 90,
                        "currency_code": "EUR"
                    },
                    "purchase_estimated_delivery_date": "2021-11-25"
                }
            ]
        }
    }
}

Error Responses Scenario :No API key HTTP/1.1 400

{
    "errorId": "CFAP-400",
    "message": "BAD_REQUEST No Api key generated for requested userId",
    "category": "APPLICATION",
    "timestamp": "Fri Mar 05 12:53:03 UTC 2021"
}

Scenario : for wrong data provided ( sample ) HTTP/1.1 400

{
    "errorId": "CFAP-400",
    "category": "APPLICATION",
    "message": "Bad Request - WRONG Country Id",
    "timestamp": "2021-02-23T06:45:44.083+0000"
}

Interest Calculation

Overview

The Interest Calculation will help the customer to calculate the interest.

Interest Calculation API will also give the total Credit (loan) amount, monthly payment details.

For calculating the interest some inputs like Credit amount, installment percentage, credit due date required.

Changes from the previous version

This is the changelog of Interest Calculation API. The topmost item is the latest version and the changes described in it are relative to the previous version which is listed directly below. The current version of the API documentation is 2.0

Swagger Definition

The Interest Calculation API specification is also available in the swagger format

Interest Calculation - This will updated by OBD ( Open banking Department)

Request Header Parameter

Sr.No.Field NameTypeMandatory InformationExample
1x-ibm-client-idStringMandatoryyou will get it from developer portal.
2x-ibm-client-secretStringMandatoryyou will get it from developer portal.
3api-keyStringMandatoryNeed to generate every time - c9483211-e8ed-490b-8238-bf2fc5823ca2

Request Body parameter: User need to add body while posting the request. The request will be in Json format and the parameters details are as below.

Sr.No.Field NameTypeMandatoryExamples
1credit_due_dayStringY1
2credit_amountdecimalY1000
3opening_feedecimalY1.23
4installment_percentdecimalY1.2
5loan_margindecimalY

Response Body

Sr.No.Field NameTypeExample
1Loan_details. annual_interest_ratedecimal12.5
2Loan_details. loan_margindecimal8
3Loan_details. base_ratedecimal-0.478
4Loan_details. euribor_ratedecimal-0.478
5Loan_details. nbr_of_monthly_paymentsdecimal103
6Loan_details. loan_amount_totaldecimal4176.15
7Loan_details. monthly_amountdecimal40
8Loan_details. euribor_monthString10
9Loan_details. euribor_yearString2020

Examples

Request Body

{
	"credit_due_day" : 23,
	"credit_amount" : 2500,
	"opening_fee" : 200,
	"installment_percent" : 1.2,
	"loan_margin" : 25
}

Response Body

{
   "message": null,
   "message_description": null,
   "loan_details":    {
      "annual_interest_rate": 13.5,
      "loan_margin": 8,
      "base_rate": -0.478,
      "euribor_rate": -0.325,
      "nbr_of_monthly_payments": 105,
      "loan_amount_total": 4176.15,
      "monthly_amount": 40,
      "euribor_month": "10",
      "euribor_year": "2020"
   }
}

Error Responses

Scenario – When no data in body to post

{
    "timestamp": "2021-05-19T10:29:18.036+0000",
    "status": 400,
    "error": "Bad Request",
    "message": "Bad Request",
    "path": "/retail-finance/credit-applications/v2/interest-calculations"
}
Retail Finance Authentication API v2Credit List API v2