Skip to main content
POST
/
v1
/
loans
/
{loanId}
/
repayments
Charge Repayment
curl --request POST \
  --url https://carbonapistagingsecure.getcarbon.co/baas/api/v1/loans/{loanId}/repayments \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --header 'x-carbon-key: <x-carbon-key>' \
  --data '
{
  "amount": 7199999,
  "reference": "REPAY_REF_20250215_001"
}
'
{
  "status": "success",
  "message": "Repayment initiated",
  "data": {}
}

​
Overview

Initiates a repayment charge for an active loan. All amounts are in kobo.
Note: The :loanId path parameter is the loan ID (field loan_id on the application record, populated after disbursement) — not the application_id.

​
Request

Method: POST
URL: /v1/loans/:loanId/repayments

​
Parameters

NameInTypeRequiredDescription
x-carbon-keyHeaderstringYesAPI key for authentication.
loanIdPathstringYesLoan ID from the application record (loan_id field).

​
Request Body

{
  "amount": 7199999,
  "reference": "REPAY_REF_20250215_001"
}
FieldTypeRequiredDescription
amountnumberYesRepayment amount in kobo. Must be positive.
referencestringYesMerchant-supplied reference for this repayment.

​
Response

​
200 OK

{
  "status": "success",
  "message": "Repayment initiated",
  "data": {}
}

​
Error Responses

StatusMessageCause
400Loan not foundloanId does not match any loan under this merchant
400amount must be a positive number (in kobo)amount is zero, negative, or not a number
400reference is requiredMissing repayment reference
422No SME loan ID on recordLoan not yet registered in lending engine

Authorizations

​
apikey
string
header
required

Provide your API key in the 'apikey' header.

Headers

​
x-carbon-key
string
required

Path Parameters

​
loanId
string
required

Loan ID from the application record (loan_id field, not application_id)

Body

application/json

Provide the required values for the request body.

​
amount
number
required

Repayment amount in kobo

Example:

7199999

​
reference
string
required

Merchant-supplied repayment reference

Example:

"REPAY_REF_20250215_001"

Response

200 - application/json

Successful response

The response is of type object.