> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcarbon.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Lending

> Enable your customers to access business loans through the Carbon Lending API.

## 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:

1. Upload file via `POST /v1/loans/:id/documents` with `file_tag = BOARD_RESOLUTION_DOC` — save the `file_url`.
2. 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](/webhooks/introduction) for delivery details and retry behaviour.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.