Skip to main content
POST
/
v1
/
loans
/
apply
Apply for Loan
curl --request POST \
  --url https://carbonapistagingsecure.getcarbon.co/baas/api/v1/loans/apply \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --header 'x-carbon-key: <x-carbon-key>' \
  --data '
{
  "customer_id": "1732ca47-42b2-4990-a65d-c369e934eed3",
  "amount": 2000000,
  "repayment_period": 3,
  "loan_purpose": "INVENTORY_MGT",
  "reference": "MERCH_REF_001"
}
'
{
  "status": "success",
  "data": {
    "application_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "PENDING"
  }
}

​
Overview

Submits a loan application for a customer whose kyc_status is VERIFIED. The reference field is a merchant-controlled idempotency key — submitting the same reference again returns the existing application with 200 OK instead of creating a duplicate. All amounts are in kobo (1 NGN = 100 kobo).

​
Request

Method: POST
URL: /v1/loans/apply

​
Parameters

NameInTypeRequiredDescription
x-carbon-keyHeaderstringYesAPI key for authentication.

​
Request Body

{
  "customer_id": "1732ca47-42b2-4990-a65d-c369e934eed3",
  "amount": 2000000,
  "repayment_period": 3,
  "loan_purpose": "INVENTORY_MGT",
  "reference": "MERCH_REF_20250115_001"
}
FieldTypeRequiredDescription
customer_idstringYesUUID of the KYC-verified customer
amountnumberYesLoan amount in kobo. Minimum: 300000 (₦3,000)
repayment_periodnumberYesRepayment duration in months. Range: 1 – 6
loan_purposestringYesSee enum below
referencestringYesMerchant idempotency key. Max 100 characters.
loan_purpose values:
ValueDescription
WORKING_CAPITALWorking capital
EXPANSION_AND_GROWTHBusiness expansion
EQUIPMENT_PURCHASEEquipment purchase
INVENTORY_MGTInventory management
DEBT_FINANCINGDebt financing
STARTUP_CAPITALStartup capital
OTHERSOther purposes

​
Response

​
201 — Application Created

{
  "status": "success",
  "message": "Loan application submitted",
  "data": {
    "application_id": "aaaabbbb-cccc-dddd-eeee-ffffffffffff",
    "status": "PENDING",
    "amount": 2000000,
    "repayment_period": 3,
    "loan_purpose": "INVENTORY_MGT",
    "created_at": "2025-01-15T10:10:00.000Z"
  }
}

​
200 — Duplicate Reference (Idempotent)

{
  "status": "failed",
  "message": "An application with this reference already exists",
  "data": {
    "application_id": "aaaabbbb-cccc-dddd-eeee-ffffffffffff",
    "status": "PENDING",
    "amount": 2000000,
    "repayment_period": 3,
    "loan_purpose": "INVENTORY_MGT",
    "created_at": "2025-01-15T10:10:00.000Z"
  }
}

​
Error Responses

StatusMessageCause
400customer_id is requiredField missing
400Customer not foundCustomer not under this merchant
400minimum loan amount is 300000 koboamount below minimum
400repayment_period must be between 1 and 6 monthsOut of range
400loan_purpose must be one of: ...Invalid enum value
400reference must be 100 characters or lessreference too long
422Customer KYC must be verified before applying for a loankyc_status is not VERIFIED

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.

​
customer_id
string
required
Example:

"1732ca47-42b2-4990-a65d-c369e934eed3"

​
amount
number
required

Loan amount in kobo

Example:

2000000

​
repayment_period
number
required

Tenure in months (1–6)

Example:

3

​
loan_purpose
string
required
Example:

"INVENTORY_MGT"

​
reference
string
required

Merchant idempotency key

Example:

"MERCH_REF_001"

Response

200 - application/json

Successful response

The response is of type object.