Shopping Loan API Integration

Authentication

Authorization is required to access the API. Bearer Token is used for authorization.

Get Token

Endpoint: /loans/authenticate Method: POST Content-Type: application/json

Request Parameters

{
  "username": "string",
  "password": "string",
  "merchantNo": 0,
  "apiSecretKey": "string"
}

Parameter	Type	Description	Required
username	string	Merchant API username	Required
password	string	Merchant API password	Required
merchantNo	integer	Merchant number	Required
apiSecretKey	string	Unique key for the merchant (provided by Nkolay)	Required

Response Example

{
  "token": "eyJhbGciOiJIUzUxMiJ9.eyJtZXJjaGFudF9ubyI6NDAwM..."
}

Using the Token

The received token value must be added to the Authorization header as Bearer in all subsequent API calls.

Example Authorization Header:

Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJtZXJjaGFudF9ubyI6NDAwM...

---

Query Banks

Returns the list of contracted banks. It is recommended to use this information to display banks on the end user’s screen.

Endpoint: /loans/v1/facilitate/query/banks Method: POST Content-Type: application/json

Request

Body can be left empty:

{}

Response Example

{
  "banks": [
    {
      "countryId": "TR",
      "code": "AKTIFBANK",
      "type": "AKTIFBANK",
      "name": "Aktif Bank",
      "description": "Aktif Yatırım Bankası A.Ş.",
      "active": true
    }
  ]
}

Response Parameters

Parameter	Type	Description
banks	array[object]	List of banks
countryId	string	Country ID
code	string	Bank code (used when starting a session)
type	string	Bank type
name	string	Bank name
description	string	Bank description
active	boolean	Whether the bank is active

---

Start Bank Session

Starts a new credit session for a specific bank. The referenceId value returned from this service will be used in subsequent API calls.

Endpoint: /loans/v1/facilitate/sessions/{bankCode} Method: POST Content-Type: application/json

Parameters

Parameter	Type	Description	Example
bankCode	string (path)	Bank code (the code value obtained from Query Banks service)	AKTIFBANK

Request

Body can be left empty:

{}

Response Example

{
  "referenceId": "7b942ca7-7ecd-4b45-9581-855a6f5c4856"
}

Response Parameters

Parameter	Type	Description
referenceId	string	Credit session reference ID. This ID will be used in payment simulation and pre-credit assessment services.

---

Payment Simulation

Simulates monthly payments for a specific credit amount and term. You can use this to show different installment options to your customer.

Endpoint: /loans/v1/facilitate/simulation/{bankSessionReferenceId} Method: POST Content-Type: application/json

Parameters

Parameter	Type	Description
bankSessionReferenceId	string (path)	The referenceId value returned from the Start Bank Session operation

Request Parameters

{
  "maxTerm": 6,
  "cart": {
    "price": {
      "itemsPrice": 20000.00,
      "shippingPrice": 100.00,
      "totalPrice": 20100.00
    },
    "items": [
      {
        "productName": "Product Name",
        "categoryCode": "Category Code",
        "quantity": 1,
        "price": 20000.00,
        "totalPriceWithoutDiscounts": 20000.00,
        "totalPrice": 20000.00
      }
    ]
  }
}

Parameter	Type	Description	Required
maxTerm	integer	Maximum number of terms	Optional
cart	object	Shopping cart information	Optional
cart.price	object	Price information	Required
cart.price.itemsPrice	number	Total price of items	Required
cart.price.shippingPrice	number	Shipping price	Required
cart.price.totalPrice	number	Total price (items + shipping)	Required
cart.items	array[object]	List of items in cart	Required
cart.items[].productName	string	Product name	Required
cart.items[].categoryCode	string	Product category code	Required
cart.items[].quantity	integer	Product quantity	Required
cart.items[].price	number	Unit price of product	Optional
cart.items[].totalPriceWithoutDiscounts	number	Total price without discounts	Required
cart.items[].totalPrice	number	Total price with discounts	Required

Response Example

{
  "bankResponseCode": "0",
  "bankResponseMessage": "Transaction Successful",
  "success": true,
  "monthlyPayments": [
    {
      "term": 3,
      "amount": 7442.8,
      "interestRate": 4.19,
      "totalPaymentAmount": 22328.38,
      "annualEffectiveInterestRate": 88.9774,
      "monthlyEffectiveInterestRate": 7.4148
    },
    {
      "term": 6,
      "amount": 4016.84,
      "interestRate": 4.19,
      "totalPaymentAmount": 24101.05,
      "annualEffectiveInterestRate": 88.9781,
      "monthlyEffectiveInterestRate": 7.4148
    }
  ]
}

Response Parameters

Parameter	Type	Description
bankResponseCode	string	Bank response code (“0” = successful)
bankResponseMessage	string	Bank response message
success	boolean	Indicates whether the operation was successful
monthlyPayments	array[object]	List of monthly payment plans
monthlyPayments[].term	integer	Number of terms (months)
monthlyPayments[].amount	number	Monthly payment amount (TL)
monthlyPayments[].interestRate	number	Interest rate (%)
monthlyPayments[].totalPaymentAmount	number	Total payment amount (TL)
monthlyPayments[].annualEffectiveInterestRate	number	Annual effective interest rate (%)
monthlyPayments[].monthlyEffectiveInterestRate	number	Monthly effective interest rate (%)

---

Pre-Credit Assessment

Queries the customer’s pre-approved credit limit by sending customer and cart information. Calling this service is mandatory before making a loan application.

Endpoint: /loans/v1/facilitate/pre-approved/{bankSessionReferenceId} Method: POST Content-Type: application/json

Parameters

Parameter	Type	Description
bankSessionReferenceId	string (path)	The referenceId value returned from the Start Bank Session operation

Request Parameters

{
  "nationalIdentityNumber": "12345678901",
  "gsmNumber": "5551234567",
  "orderId": "ORDER-12345",
  "maxTerm": 6,
  "cart": {
    "price": {
      "itemsPrice": 20000.00,
      "shippingPrice": 100.00,
      "totalPrice": 20100.00
    },
    "items": [
      {
        "productName": "Product Name",
        "categoryCode": "Category Code",
        "quantity": 1,
        "price": 20000.00,
        "totalPriceWithoutDiscounts": 20000.00,
        "totalPrice": 20000.00,
        "sellerExternalId": "SELLER-001",
        "commissionRate": 1.00,
        "withholdingTax": 0.10,
        "marketplaceCost": 2.00
      }
    ]
  }
}

Parameter	Type	Description	Required
nationalIdentityNumber	string	Customer’s national ID number (11 digits)	Required
gsmNumber	string	Customer’s phone number (5XXXXXXXXX format)	Required
orderId	string	Order number (must be unique)	Required
maxTerm	integer	Desired maximum number of terms	Required
cart	object	Cart information	Required
cart.items[].sellerExternalId	string	Seller ID (for marketplace)	Optional
cart.items[].commissionRate	number	Commission rate (%)	Optional*
cart.items[].commissionAmount	number	Commission amount (TL)	Optional*
cart.items[].withholdingTax	number	Withholding tax	Optional
cart.items[].marketplaceCost	number	Marketplace cost	Optional

Note: Only one of commissionRate and commissionAmount fields should be filled.

Response Example

{
  "success": true,
  "referenceId": "50171152-66c5-4374-9f82-6a97c9e6d5d0",
  "bankSuccess": true,
  "bankResponseCode": "0",
  "bankResponseMessage": "Transaction Successful",
  "monthlyPayments": [
    {
      "term": 3,
      "interestRate": 4.19,
      "amount": 7442.8,
      "totalPaymentAmount": 22328.38,
      "annualEffectiveInterestRate": 88.9774,
      "type": "CONSUMER_LOAN"
    }
  ]
}

Response Parameters

Parameter	Type	Description
success	boolean	Indicates whether the operation was successful
referenceId	string	Reference ID. This ID will be used in the loan application service.
bankSuccess	boolean	Indicates whether it was approved by the bank
bankResponseCode	string	Bank response code
bankResponseMessage	string	Bank response message
monthlyPayments	array[object]	Monthly payment plan (same format as Simulation service)
monthlyPayments[].type	string	Loan type (e.g., CONSUMER_LOAN)

---

Integration Flow

Follow this sequence to complete the shopping loan integration:

1. Authentication - Get Bearer Token
2. Query Banks - Get the list of banks to show to the customer
3. Start Bank Session - Start a session for the selected bank
4. Payment Simulation (Optional) - Show different term options
5. Pre-Credit Assessment - Check customer’s credit eligibility
6. Loan Application - Next step →

Next Steps

• Loan Application and Management → - Application submission, querying and refund operations