# Overview

The Disbursement Service is where money moves. Once your users are onboarded through the Onboarding Service, the Disbursement Service lets you create loans, disburse funds to bank accounts, track repayments, and manage the full lifecycle of lending — all through a single set of APIs.

Whether you are building a digital lender, a buy-now-pay-later product, or an employer salary-advance platform, this service gives you the building blocks to move money out to your users and track every naira back in.

### How it works

***

At a high level, a typical disbursement integration follows this flow:

1. **Create a loan** — Define the loan terms: amount, duration, interest rate, repayment frequency, and currency. Tendar computes the repayment schedule for you.
2. **Set up a beneficiary** — Register the user's bank account, verify it, and link it as the disbursement destination.
3. **Disburse the loan** — Send the approved loan amount to the user's bank account, either manually or through a supported payment provider.
4. **Track repayments** — Tendar automatically generates a repayment schedule when a loan is disbursed. You can list, fetch, and monitor repayment progress.
5. **Handle transfers** — Need to move funds outside the context of a loan? Use the Transfer API to send money directly to a verified beneficiary.

```
  Create Loan ──▶ Add Beneficiary ──▶ Disburse ──▶ Track Repayments
                                          │
                                          ▼
                                   Transfer Funds
```

### Base URL

***

All Disbursement Service endpoints are served under:

Production:

```bash
https://api.tendar.co/disbursement
```

Sandbox

```bash
https://tendar-disbursement-dev-v2.fly.dev
```

### Core concepts

***

#### Loans

A loan is the central object in the Disbursement Service. It captures the amount requested, the interest model (flat, reducing balance, or fixed), the repayment schedule, and the disbursement status. You can create a loan, edit its terms before approval, reject it, or counter it with an alternative offer.

Tendar supports three interest types:

| Interest type      | How it works                                                            |
| ------------------ | ----------------------------------------------------------------------- |
| `flat`             | Interest is calculated on the full principal for each repayment cycle.  |
| `reducing_balance` | Interest is recalculated on the outstanding balance after each payment. |
| `fixed`            | A one-time interest charge applied to the principal.                    |

When you create a loan, Tendar automatically calculates the repayment frequency, total interest, amount repayable, and the instalment amount — so you do not have to build that math into your own system.

#### Beneficiaries (Bank Accounts)

Before you can disburse or transfer funds, the recipient needs a verified bank account on file. The Beneficiary API lets you:

* List supported banks for a given country.
* Resolve an account number to confirm the account name.
* Create a beneficiary record linked to a user.
* Verify the beneficiary through an OTP flow.
* Set a default beneficiary for a user.

#### Disbursements

A disbursement is the act of sending an approved loan amount to the user. You can disburse with or without a payment provider. When you disburse **with a provider**, Tendar initiates the bank transfer through that a provider and tracks the status. When you disburse **without a provider**, you record the disbursement manually after handling the payout on your end.

#### Repayments

Once a loan is disbursed, Tendar generates a repayment schedule — a series of repayment records, each with a due date and an amount. You can fetch repayment offers before creating a loan to show your users what their instalment options look like, and you can configure repayment options (min/max amounts, interest rates, duration ranges) for your platform.

#### Counter Loans

Sometimes a loan request does not meet your criteria as-is. Instead of rejecting it outright, you can create a **counter loan** — an alternative offer with a different amount, interest rate, or purpose. The user can then accept or reject the counter offer.

#### Transfers

Transfers let you move money to a verified beneficiary outside the context of a loan. This is useful for refunds, payouts, or any scenario where you need to send funds to a user's bank account directly.

#### Transactions

Every financial movement — disbursements and recollections — is recorded as a transaction. You can list and export transactions for reconciliation, reporting, or auditing.

### Before you begin

***

Make sure you have completed the following:

* **Onboarded your users** — Users must exist in the [Onboarding Service](https://docs.tendar.co/documentation/onboarding) before you reference them in the Disbursement Service. Each user is identified by their `user_id` (e.g. `usr-xxxxxxxxxx`).
* **Obtained your secret key** — All requests require a Bearer token in the `Authorization` header:

```
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx
```

### What to build next

***

Each feature of the Disbursement Service has its own detailed guide. Here is the recommended reading order:

| Guide                                                                           | What you will learn                                       |
| ------------------------------------------------------------------------------- | --------------------------------------------------------- |
| [Loans](https://docs.tendar.co/documentation/disbursement/loans)                | Create, edit, reject, and manage the full loan lifecycle. |
| [Disbursements](https://docs.tendar.co/documentation/disbursement/disbursement) | Disburse approved loans to bank accounts.                 |
| [Repayments](https://docs.tendar.co/documentation/disbursement/repayment)       | Understand repayment schedules, offers, and options.      |
| [Beneficiaries](https://docs.tendar.co/documentation/disbursement/beneficiary)  | Register and verify user bank accounts.                   |
| [Transfers](https://docs.tendar.co/documentation/disbursement/transfers)        | Send money directly to a beneficiary.                     |
| [Transactions](https://docs.tendar.co/documentation/disbursement/transactions)  | Query and export all financial activity.                  |

### Quick example: Create and disburse a loan

***

Below is a quick walkthrough to help you understand the integration. Detailed request and response schemas are covered in the individual guides.

#### 1. Create a loan

```bash
curl -X POST {{disbursement}}/loan/create \
  -H "Authorization: Bearer sk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr-dcloimuzin",
    "purpose": "daily consumption",
    "duration_type": "monthly",
    "duration": 4,
    "frequency": 1,
    "frequency_type": "monthly",
    "interest_rate": 10,
    "amount": 10000,
    "currency": "NGN",
    "interest_type": "flat",
    "pay_interest_after": true,
    "disburse": false,
    "metadata": {}
  }'
```

#### 2. Add a beneficiary

```bash
curl -X POST {{disbursement}}/beneficiary/create \
  -H "Authorization: Bearer sk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr-dcloimuzin",
    "account": {
      "account_number": "0337780258",
      "account_name": "JOHN DOE",
      "bank_code": "058"
    },
    "currency": "NGN"
  }'
```

#### 3. Disburse the loan

```bash
curl -X POST {{disbursement}}/disbursement/create?user_id=usr-dcloimuzin \
  -H "Authorization: Bearer sk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "loan": "<loan_id>",
    "with_provider": false,
    "next_pay_date": "",
    "callback_url": ""
  }'
```

Once disbursed, Tendar marks the loan as accepted, generates the repayment schedule, and records the transaction — all automatically.