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