Quickstart

This guide gets you from zero to your first successful API call.

1. Get an API key

Self-service keys are issued from the customer dashboard: Settings → API. A key is scoped either to your whole tenant or to a single customer/business, and carries one or more scopes (onboarding:read/write, accounts:read, webhooks:read/write, and more depending on which generation of the API you're using — see Authentication & scopes).

If you don't have dashboard access yet, or need a scope the dashboard doesn't self-serve, contact your KwiikPay account manager.

2. Make your first call

Every request needs your key in the X-Api-Key header:

curl https://api.kwiikpay.io/api/v2/public/customers \
  -H "X-Api-Key: kwp_live_..."

A successful response looks like:

{
  "items": [
    { "recordType": "Customer", "externalReference": "customer-123", "displayName": "Jane Doe", "lifecycleStatus": "Active", "...": "..." }
  ],
  "count": 1,
  "limit": 100
}

(/api/v2/public bodies are camelCase; /api/v1/partner bodies are snake_case — see the note in Errors and Webhooks about the two generations not having converged on one wire format yet.)

3. Which API surface should I use?

KwiikPay currently runs two API generations side by side:

• /api/v2/public/... — read-only visibility into customers and fiat accounts, plus outbound webhook subscription management. Use this if you already have customers provisioned (through the dashboard or /api/v1/partner) and want to read their state or react to events without polling.
• /api/v1/partner/... — the full surface: creating customers, running KYC/KYB, opening fiat accounts, moving money (withdrawals, exchange/conversion), payout batches. Use this for anything that creates or mutates a customer or their funds.

If you're not sure, start with /api/v1/partner — it's the surface that can actually onboard a customer and move money. /api/v2/public is a read/webhook companion to it, not a replacement.

4. Next steps

• Authentication & scopes — how keys, scopes, and subject-binding work.
• Idempotency — every mutating call needs this header.
• Webhooks — react to events instead of polling.
• Full endpoint reference: API Reference (v1) or API Reference (v2).