Lending

Overview

The Carbon Lending API allows fintech partners to originate business loans for their own end-customers. The full flow — from customer enrollment through repayment — is orchestrated via REST API with webhook notifications at every lifecycle event.

Flow

Customer  ────►  Account  ────►  Enroll  ────►  KYC  ────►  Apply  ────►  Underwriting
                                                                                 │
                                                                                 ▼
Repayment  ◄────  Disburse  ◄────  Post-offer KYC  ◄────  Offer

Step-by-step

Step	Action	Endpoint
0	Create the customer record	`POST /v1/customers`
1	Create a Carbon account for the customer	`POST /v1/accounts`
2	Enroll customer for lending	`POST /v1/loans/customers/enroll`
3	Trigger KYC verification	`POST /v1/loans/customers/:id/verify-kyc`
4	Poll KYC until `VERIFIED`	`GET /v1/loans/customers/:id/kyc-status`
5	Submit loan application	`POST /v1/loans/apply`
6	Submit business profile data	`POST /v1/loans/:id/submit-underwriting`
7	Request bank statement	`POST /v1/loans/:id/bank-statement`
8	Upload supporting documents	`POST /v1/loans/:id/documents`
9	Start credit decisioning	`POST /v1/loans/:id/start-decisioning`
10	Poll until `HAS_OFFER`	`GET /v1/loans/:id`
11	Fetch offer details	`GET /v1/loans/:id/offer`
12	Set disbursement account	`POST /v1/loans/:id/disbursement-account`
13	Accept offer	`POST /v1/loans/:id/offer/accept`
14	Agree to terms	`POST /v1/loans/:id/terms/agree`
15	Upload board resolution (non-sole-prop)	`POST /v1/loans/:id/board-resolution`
16	Add guarantor (if required)	`POST /v1/loans/:id/guarantor`
17	Complete post-offer KYC	`POST /v1/loans/:id/post-offer-kyc`
—	Carbon admin disburses	(internal)
18	Charge repayments	`POST /v1/loans/:loanId/repayments`

Key Concepts

Amounts

All monetary values are in kobo. Divide by 100 to get Naira.

300,000 kobo = ₦3,000

`application_id` vs `loan_id`

application_id — UUID created when POST /v1/loans/apply succeeds. Used in all loan operation routes (:applicationId).
loan_id — Populated after disbursement. Used only for repayment routes (:loanId).

Idempotency

Endpoint	Key
`POST /v1/loans/customers/enroll`	`customer_id`
`POST /v1/loans/apply`	`reference`

Resending the same key returns the existing record rather than creating a duplicate.

Board Resolution

Required for all business customers except sole proprietors. Two-step process:

Upload file via POST /v1/loans/:id/documents with file_tag = BOARD_RESOLUTION_DOC — save the file_url.
Pass file_url to POST /v1/loans/:id/board-resolution.

Webhooks

Subscribe to real-time loan events via the webhook system. Each status change fires an event to your registered webhook URL.

Event	Trigger
`loan.application.received`	Application submitted
`loan.kyc.pending`	KYC verification started
`loan.offer.generated`	Offer ready
`loan.offer.accepted`	Offer accepted
`loan.offer.declined`	Offer declined
`loan.offer.expired`	Offer expired
`loan.application.declined`	Application rejected
`loan.application.approved`	Approved for disbursement
`loan.disbursed`	Funds disbursed
`loan.arrears`	Loan in arrears
`loan.closed`	Loan fully repaid

See the Webhooks guide for delivery details and retry behaviour.

Get Started

Payment Operations

Webhooks

Plugins & Sdks

Lending

Overview

Flow

Step-by-step

Key Concepts

Amounts

`application_id` vs `loan_id`

Idempotency

Board Resolution

Webhooks

​Overview

​Flow

​Step-by-step

​Key Concepts

​Amounts

​application_id vs loan_id

​Idempotency

​Board Resolution

​Webhooks

Overview

Flow

Step-by-step

Key Concepts

Amounts

`application_id` vs `loan_id`

Idempotency

Board Resolution

Webhooks