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

# Introduction

> Accept and disburse mobile-money payments across Mali with the Kori Merchant API.

The **Kori Merchant API** lets your application collect payments from customers,
disburse funds, run payouts and bulk payments, create payment links, and manage your
team — all over mobile money (Orange Money, Wave, Sama, Moov).

Everything documented here is reachable with a **merchant API key**, using exactly the
permissions ("scopes") you see in the **API Keys** screen of your Kori dashboard.

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Make your first authenticated request in a few minutes.
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Exchange your API key + secret for a scoped Bearer token.
  </Card>

  <Card title="Scopes" icon="shield-check" href="/scopes">
    Understand what each API key permission grants.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Full endpoint reference with request/response schemas.
  </Card>
</CardGroup>

## Base URL

<CodeGroup>
  ```bash Production theme={null}
  https://api.kori.ml
  ```

  ```bash Sandbox theme={null}
  https://dev.kori.ml
  ```
</CodeGroup>

All merchant endpoints are served under the `/merchant/api` path, e.g.
`https://api.kori.ml/merchant/api/balance`.

## How it works

<Steps>
  <Step title="Create an API key">
    In the dashboard, open **API Keys** and create a key. Choose the scopes it should
    carry (for example `pay`, `balance`, `webhooks`). You receive an API **key**
    (`mk_...`) and **secret** (`ms_...`).
  </Step>

  <Step title="Get a token">
    Call [`POST /merchant/api/auth`](/authentication) with your key and secret to
    receive a short-lived Bearer token embedding your scopes.
  </Step>

  <Step title="Call the API">
    Send the token as `Authorization: Bearer <token>` on every request. Each endpoint
    checks for its required scope.
  </Step>

  <Step title="Receive webhooks">
    Register a [webhook](/webhooks) endpoint to be notified when payments settle,
    payouts complete, and more.
  </Step>
</Steps>

## Response format

Every response uses the same envelope:

```json theme={null}
{
  "success": true,
  "message": "Balance retrieved successfully",
  "request_id": "b2f1c3a0-...",
  "data": { "...": "..." }
}
```

Errors set `success: false` with a human-readable `message`. See [Errors](/errors).

<Note>
  **Collections are asynchronous.** `POST /merchant/api/pay` returns `202` with
  `status: "pending"` — the customer has only been prompted. Treat an order as paid only
  after the `payment_received` webhook. See [Webhooks](/webhooks).
</Note>