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

# Quickstart

> Get started with Kotani Pay API v3 in minutes

## Prerequisites

You need a Kotani Pay integrator account. **Sandbox accounts are self-service** — <a href="https://integrator.kotanipay.com/register" target="_blank">register now on the Kotani Pay dashboard</a>. Production accounts require a provisioned account from the Kotani Pay team.

***

## 1. Get Your API Key

The fastest way is from the dashboard — no code required.

1. Log in to [integrator.kotanipay.com](https://integrator.kotanipay.com)
2. Navigate to **API Keys** in the left sidebar
3. Click **Generate New Key**
4. Copy and store the key securely — it won't be shown again

<Note>
  If you need a key with a signing secret (for webhook payload verification), use **Generate Secure Key** instead. This returns both a `key` and a `secret`. See [API Keys](/v3/getting-started/api-keys) for the difference.
</Note>

**Prefer the API?** You can also generate a key programmatically via a magic link flow — see [API Keys](/v3/getting-started/api-keys) for that method.

***

## 2. Make Your First Call

Use the API key in the `Authorization: Bearer` header:

```bash theme={null}
curl -X GET https://sandbox-api.kotanipay.io/health \
  -H "Authorization: Bearer <your-api-key>"
```

A successful response confirms your key is valid:

```json theme={null}
{
  "success": true,
  "message": "Health check",
  "data": {
    "status": "ok"
  }
}
```

***

## 3. Pick Your Flow

Now that you have a key, choose what you're building:

<CardGroup cols={2}>
  <Card title="Collect payments" icon="arrow-down" href="/v3/flows/deposit-flow">
    Customer pays you via mobile money, bank checkout, or card. Funds land in your deposit balance.
  </Card>

  <Card title="Disburse funds" icon="arrow-up" href="/v3/flows/withdrawal-flow">
    Send money to a customer's mobile money wallet or bank account from your payout balance.
  </Card>

  <Card title="Buy crypto (Onramp)" icon="coins" href="/v3/flows/onramp-flow">
    Customer pays fiat via mobile money or bank; Kotani Pay sends crypto to their wallet.
  </Card>

  <Card title="Sell crypto (Offramp)" icon="arrow-right-arrow-left" href="/v3/flows/offramp-flow">
    Customer sends crypto to an escrow address; Kotani Pay disburses fiat to their mobile money or bank.
  </Card>

  <Card title="Payment links" icon="link" href="/v3/flows/payment-links-flow">
    Generate a hosted checkout page — no frontend required. Share the URL and start collecting.
  </Card>

  <Card title="Bulk payments" icon="list" href="/v3/flows/bulk-payments-flow">
    Disburse to hundreds of recipients at once via CSV upload — payroll, commissions, refunds.
  </Card>
</CardGroup>

***

## 4. Fund Your Payout Balance

<Note>
  Only needed if you're sending money out — withdrawals, offramp, or bulk payments.
</Note>

Deposits credit your **deposit balance**. Withdrawals draw from your **payout balance**. These are separate — you need to transfer between them before you can disburse.

In the dashboard: **Wallets → Transfer Deposit Balance**

See [Balances & Settlement](/v3/essentials/balances-and-settlement) for the full explanation.

***

## 5. Set Up Webhooks

Every transaction request accepts a `callbackUrl` — Kotani Pay posts the result directly to that URL when the transaction settles. No extra configuration needed for this.

If you want callbacks to arrive with a signature you can verify, configure a webhook secret:

1. Log in to the dashboard → **Settings**
2. Copy the generated signing secret and store it as an environment variable

With a secret configured, every callback includes `X-Kotani-Signature`, `X-Kotani-Event`, and `X-Kotani-Integrator` headers. See [Webhooks](/v3/essentials/webhooks) for both delivery modes, payload structures, and signature verification.

***

## 6. Go Live

1. **Contact Kotani Pay** via your usual communication channel to request a production account
2. Once provisioned, log in to [integrator.kotanipay.com](https://integrator.kotanipay.com) and switch to **Production** using the environment selector in the top right
3. Generate a production API key from **API Keys** in the sidebar
4. Switch your base URL to `https://api.kotanipay.io`

<Note>
  See [Accessing the Dashboard](/v3/getting-started/dashboard-login) for how the environment gate and selector work.
</Note>

<Warning>
  Sandbox credentials do not work in production and vice versa. Always confirm the environment is set correctly before going live.
</Warning>