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

Three ways, in order of preference — see 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:

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:

curl https://api.kori.ml/merchant/api/payment/status/order_1024

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

Scopes

See every permission an API key can grant.

Webhooks

Get notified when payments settle.

Payment status

Pending, success or failed — and how to tell them apart.

Get Started

Guides

Prerequisites

1. Get a token

2. Check your balance

3. Collect a payment

4. Check the payment status

Next steps

Scopes

Webhooks

Payment status

​Prerequisites

​1. Get a token

​2. Check your balance

​3. Collect a payment

​4. Check the payment status

​Next steps

Scopes

Webhooks

Payment status

Prerequisites

1. Get a token

2. Check your balance

3. Collect a payment

4. Check the payment status

Next steps