Quickstart

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.

Use the Sandbox base URL https://dev.kori.ml while testing.

1. Get a token

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

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 }'

Response

{
  "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

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.

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"
  }'

Response (202 Accepted)

{
  "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
  }
}

status: "pending" means the prompt was sent, not that the customer paid. Do not fulfill the order yet.

4. Confirm settlement

Wait for the payment_received webhook, or poll the transaction:

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.

Get Started

Guides

Prerequisites

1. Get a token

2. Check your balance

3. Collect a payment

4. Confirm settlement

Next steps

Scopes

Webhooks

​Prerequisites

​1. Get a token

​2. Check your balance

​3. Collect a payment

​4. Confirm settlement

​Next steps

Scopes

Webhooks

Prerequisites

1. Get a token

2. Check your balance

3. Collect a payment

4. Confirm settlement

Next steps