> ## 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": "XOF",
    "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. Check the payment status

Three ways, in order of preference — see [Payment status](/en/payment-status) for the full
picture.

**Wait for the webhook.** Subscribe to `payment_received` and Kori tells you:
no polling, and it arrives even if the customer closes the tab.

**Read your transaction record:**

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

**Or ask the operator right now**, by `reference` — authoritative while the payment is
still open, and needs no token, so a checkout page can poll it from the browser:

```bash theme={null}
curl https://api.kori.ml/merchant/api/payment/status/order_1024
```

```json theme={null}
{ "message": "SUCCESS", "state": "success", "status": true }
```

When the status is `success`, the funds are credited to your balance and you can fulfill
the order. While it is `pending` the customer simply has not answered yet — that is not
a failure, so keep waiting rather than retrying the charge.

## Next steps

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

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

  <Card title="Payment status" icon="clock" href="/en/payment-status">
    Pending, success or failed — and how to tell them apart.
  </Card>
</CardGroup>