Loan Calculator API Documentation

V1

/api/v1

First stable version for installment and tax schedule calculations.

GET /api/v1/loan/calculate Auth Required

Calculate Loan Schedule

Returns a full payment schedule with principal, interest, BSMV, KKDF, and total installment amounts for each month.

Authentication

X-Api-Key: your_api_key

Query Parameters

Name	Type	Required	Example	Description
`amount`	number	required	`10000`	Loan principal amount in TRY.
`term_months`	integer	required	`24`	Repayment term in months.
`monthly_interest_rate_percent`	number	required	`4.8`	Nominal monthly interest rate percentage before taxes.
`bsmv_rate_percent`	number	optional	`15`	Optional BSMV rate percentage. Defaults to 15.
`kkdf_rate_percent`	number	optional	`15`	Optional KKDF rate percentage. Defaults to 15.

Request Example

GET /api/v1/loan/calculate?amount=10000&term_months=24&monthly_interest_rate_percent=4.8

Response Example

{
    "success": true,
    "message": "Loan payment schedule calculated successfully.",
    "data": {
        "amount": 10000,
        "currency": "TRY",
        "term_months": 24,
        "monthly_interest_rate_percent": 4.8,
        "effective_monthly_rate_percent": 6.24,
        "taxes": {
            "bsmv_rate_percent": 15,
            "kkdf_rate_percent": 15,
            "total_tax_rate_percent": 30,
            "calculation_basis": "Taxes are calculated on the accrued interest amount of each installment."
        },
        "summary": {
            "regular_installment_amount": 814.55,
            "total_principal": 10000,
            "total_interest": 7345.49,
            "total_bsmv": 1101.82,
            "total_kkdf": 1101.82,
            "total_tax": 2203.64,
            "total_payment": 19549.13
        },
        "formula": {
            "gross_monthly_rate": "gross_rate = monthly_interest_rate x (1 + bsmv_rate + kkdf_rate)",
            "installment": "installment = amount x [gross_rate x (1 + gross_rate)^n] / [(1 + gross_rate)^n - 1]",
            "interest": "interest = opening_balance x monthly_interest_rate",
            "bsmv": "bsmv = interest x bsmv_rate",
            "kkdf": "kkdf = interest x kkdf_rate",
            "principal": "principal = installment - interest - bsmv - kkdf"
        },
        "schedule": [
            {
                "installment_number": 1,
                "opening_balance": 10000,
                "principal": 190.55,
                "interest": 480,
                "bsmv": 72,
                "kkdf": 72,
                "tax_total": 144,
                "installment_amount": 814.55,
                "closing_balance": 9809.45
            },
            {
                "installment_number": 2,
                "opening_balance": 9809.45,
                "principal": 202.44,
                "interest": 470.85,
                "bsmv": 70.63,
                "kkdf": 70.63,
                "tax_total": 141.26,
                "installment_amount": 814.55,
                "closing_balance": 9607.01
            }
        ]
    }
}

Error Response

{
    "success": false,
    "message": "The amount field is required.",
    "error_code": "VALIDATION_ERROR"
}