Skip to main content
POST
/
v1
/
loans
/
calculate-repayment
Calculate Repayment
curl --request POST \
  --url https://carbonapistagingsecure.getcarbon.co/baas/api/v1/loans/calculate-repayment \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --header 'x-carbon-key: <x-carbon-key>' \
  --data '
{
  "loan_amount": 2000000,
  "tenure": 3,
  "state": "LAGOS STATE"
}
'
{
  "status": "success",
  "data": {
    "monthly_repayment": 719999,
    "total_repayment": 2159997,
    "interest_rate": 8,
    "schedule": [
      {
        "month": 1,
        "principal": 666666,
        "interest": 53333,
        "total": 719999
      }
    ]
  }
}

​
Overview

Returns a projected repayment schedule for a given loan amount, tenure, and state. Can be called at any point — no active application is required. Useful for showing customers a preview before they apply. All amounts are in kobo.

​
Request

Method: POST
URL: /v1/loans/calculate-repayment

​
Parameters

NameInTypeRequiredDescription
x-carbon-keyHeaderstringYesAPI key for authentication.

​
Request Body

{
  "loan_amount": 2000000,
  "tenure": 3,
  "state": "Lagos"
}
FieldTypeRequiredDescription
loan_amountnumberYesLoan amount in kobo
tenurenumberYesRepayment period in months (positive integer)
statestringYesNigerian state name (affects rate)

​
Response

​
200 OK

{
  "status": "success",
  "message": "Repayment calculated",
  "data": {
    "monthlyRepayment": 720000,
    "totalRepayment": 2160000,
    "interestRate": 8.0,
    "schedule": [
      {
        "dueDate": "2025-02-15",
        "principalDue": 666666,
        "interestDue": 53333,
        "totalDue": 719999
      }
    ]
  }
}

​
Error Responses

StatusMessageCause
400loan_amount must be a number (in kobo)Missing or invalid type
400tenure must be a positive integer (months)Invalid tenure
400state is requiredMissing state

Authorizations

​
apikey
string
header
required

Provide your API key in the 'apikey' header.

Headers

​
x-carbon-key
string
required

Body

application/json

Provide the required values for the request body.

​
loan_amount
number
required
Example:

2000000

​
tenure
number
required
Example:

3

​
state
string
required
Example:

"LAGOS STATE"

Response

200 - application/json

Successful response

The response is of type object.