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

# Quickstart

> Authenticate and collect your first payment.

This guide takes you from an API key to a live collection in four requests.

## Prerequisites

* A Kori merchant account with an **API key** and **secret** (dashboard → **API Keys**).
* The key must include the scopes you intend to use here: `pay` and `balance`.

<Tip>
  Use the **Sandbox** base URL `https://dev.kori.ml` while testing.
</Tip>

## 1. Get a token

Exchange your key + secret for a Bearer token. Request only the scopes you need.

```bash theme={null}
curl -X POST https://api.kori.ml/merchant/api/auth \
  -H "X-API-Key: mk_your_api_key" \
  -H "X-API-Secret: ms_your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{ "scopes": ["pay", "balance"], "expires_in_hours": 24 }'
```

```json Response theme={null}
{
  "success": true,
  "message": "Authentication successful",
  "data": {
    "token": "eyJhbGciOiJIUzI1Ni...",
    "token_type": "Bearer",
    "scopes": ["pay", "balance"],
    "expires_in": 86400,
    "expires_at": "2026-08-09T12:00:00.000Z"
  }
}
```

Save `data.token` — you'll send it on every subsequent request.

## 2. Check your balance

```bash theme={null}
curl https://api.kori.ml/merchant/api/balance \
  -H "Authorization: Bearer <token>"
```

## 3. Collect a payment

This prompts the customer's phone to approve the payment.

```bash theme={null}
curl -X POST https://api.kori.ml/merchant/api/pay \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "payment_method": "OrangeMoney",
    "customer_phone": "+22370000000",
    "reference": "order_1024",
    "description": "Order #1024"
  }'
```

```json Response (202 Accepted) theme={null}
{
  "success": true,
  "message": "Payment initiated. Awaiting customer confirmation.",
  "data": {
    "transaction_id": 88213,
    "reference": "order_1024",
    "amount": 5000,
    "currency": "USD",
    "payment_method": "OrangeMoney",
    "status": "pending",
    "payment_url": null
  }
}
```

<Warning>
  `status: "pending"` means the prompt was sent, **not** that the customer paid. Do not
  fulfill the order yet.
</Warning>

## 4. Confirm settlement

Wait for the `payment_received` [webhook](/webhooks), or poll the transaction:

```bash theme={null}
curl https://api.kori.ml/merchant/api/transactions/88213 \
  -H "Authorization: Bearer <token>"
```

When `status` becomes `success`, the funds are credited to your balance and you can
fulfill the order.

## Next steps

<CardGroup cols={2}>
  <Card title="Scopes" icon="shield-check" href="/scopes">
    See every permission an API key can grant.
  </Card>

  <Card title="Webhooks" icon="bell" href="/webhooks">
    Get notified when payments settle.
  </Card>
</CardGroup>