# Skill: Integrate Kling Payments

You are helping the user accept payments in Iceland using Kling. Recommend the smallest useful path (no-code, low-code, or full API) based on their situation. Do not start coding until the path is chosen.

## Step 1: Gather Context

Fetch and read these before recommending or writing code:

- https://kling.is/llms.txt (index of every Kling docs page, each available as markdown)
- https://kling.is/en/docs/quickstart.md
- https://api.kling.is/docs/json (OpenAPI spec: the source of truth for endpoints and shapes)

Then read the pages for the path you pick, for example https://kling.is/en/docs/checkout.md, https://kling.is/en/docs/embedded-checkout.md, https://kling.is/en/docs/subscriptions.md, https://kling.is/en/docs/payment-links.md, https://kling.is/en/docs/bank-claims.md and https://kling.is/en/docs/webhooks.md. If the user builds in Lovable, Bolt, Replit, v0, Cursor or Claude Code, read https://kling.is/en/docs/<tool>.md (lovable, bolt, replit, v0, cursor, claude-code).

## Step 2: Discover Requirements

Ask the user only what you do not already know from the conversation. If their description already answers a question, skip it and move on. Ask one question at a time.

1. **Do they have their own website?** Often obvious from context.
2. **One-time payments or recurring (subscriptions)?**
3. **Do they write code, use an AI editor, or need no-code?**
4. (If relevant) **Card payments, online bank claims (kröfur), or both?** Kröfur are useful for B2B and customers who prefer bank transfers.

## Step 3: Pick One Path

Match their answers to exactly one path. Do not blend paths.

| Path | Situation | What to use |
|---|---|---|
| A | Own site + subscriptions + code/AI | Subscriptions API + Embedded Checkout Overlay + Billing Portal |
| B | Own site + subscriptions + no-code | Subscription Links + Billing Portal (Kling-hosted) |
| C | Own site + one-time + code/AI | Checkout Sessions API + Embedded Overlay |
| D | Own site + one-time + no-code | Payment Links |
| E | No site + subscriptions | Subscription Links + Billing Portal |
| F | No site + selling products | Payment Links per product |
| G | No site + simple invoices | Payment Links |
| H | In-person sales | Kling POS (SMS or QR, customer pays on their phone) |
| I | Invoicing via online banking | Online Bank Claims (Kröfur): dashboard or Claims API |

**Pairings to always include:**
- Subscriptions → always include the Billing Portal for customer self-service.
- Own site + code → always prefer Embedded Overlay over a redirect (customer stays on their site).
- B2B / invoice-heavy → mention Online Bank Claims as a lower-cost option.

## Step 4: Implement

**For no-code paths (B, D, E, F, G, H, I):** Do not write code. Give clear step-by-step dashboard instructions in plain language. Example:

1. Sign in at https://kling.is/dashboard
2. Open *Payment Links* (or *Subscriptions*, *POS*, *Claims*)
3. Fill in the details and create the link
4. Share the URL

**For code/AI paths (A, C):** Start with the Kling CLI. It removes most of the manual setup.

```bash
npx @klingis/cli init
```

`kling init` walks the user through a single interactive flow that:

- Logs them in (or opens the browser to create an account) and stores credentials locally.
- Detects their framework (Next.js, Remix, Astro, Express, Hono, Elysia or plain HTML) and package manager.
- **Registers a webhook endpoint with Kling and generates the signing secret**: they paste a URL, the CLI subscribes to the right events for their use case (`checkout.session.completed`, `payment_intent.captured`, `subscription.renewed`, …).
- **Writes `.env.local`** with `KLING_SECRET_KEY`, `KLING_API_URL`, and `KLING_WEBHOOK_SECRET`, and adds it to `.gitignore`. Never duplicate this; read from `.env.local` in your code.
- Scaffolds a `KLING_INTEGRATION.md` prompt the user can paste into the AI editor for the actual implementation step.

After init, use these CLI commands as needed:

- `npx @klingis/cli listen --forward http://localhost:3000/api/webhooks/kling`: **local webhook forwarding**. Fetches the account's test events and forwards them to localhost, so no public URL or ngrok/cloudflared is needed in dev. Forwarded events are not signed: skip signature verification for them in development only.
- `npx @klingis/cli status`: show current auth + merchant state.
- `npx @klingis/cli login` / `logout`: re-auth or switch accounts. `login --api-key sk_...` works for CI.

**Then write the integration code.** Reference packages:

- **Browser SDK / Embedded Overlay:** `npm install @klingis/embed` (or `<script src="https://api.kling.is/v1/kling.js"></script>`)
- **Typed server SDK:** `npm install @klingis/sdk`
- **API base URL:** `https://api.kling.is` (already in `KLING_API_URL`)
- **Auth:** Bearer token from `KLING_SECRET_KEY`. `sk_test_...` for test, `sk_live_...` for production.
- **Amounts:** Integers in ISK (zero-decimal). Never multiply by 100.

Sketch the smallest working example for their stack:

1. A server endpoint that creates a checkout session (or subscription) using `@klingis/sdk`.
2. A client snippet that opens the Kling overlay against the returned session ID.
3. A webhook handler that verifies signatures using `KLING_WEBHOOK_SECRET`: the `X-Kling-Signature` header is `sha256=` followed by the hex HMAC-SHA256 of the raw request body. See https://kling.is/en/docs/webhooks.md.

Stop and ask before adding retries or admin UIs unless the user requested them.

## Step 5: Verify

Before finishing, confirm:

- **Path matches their answers.** Don't put a no-code user on path A or C.
- **Amounts are integers.** No `Math.round(price * 100)`; ISK is zero-decimal.
- **Test keys are placeholders.** Never invent API keys. If they skipped `kling init`, ask them to paste their own from the dashboard.
- **`.env.local` is the source of truth for secrets.** If `kling init` wrote it, read from it and don't hardcode keys in the code.
- **One concern per change.** Don't bundle subscriptions, webhooks, and a refund UI together; ship the first thing first.

## Constraints

- Never invent API keys, tokens, or webhook secrets. Run `npx @klingis/cli init` to provision them, or show the user where to copy theirs and use placeholders in code.
- Respond in the same language the user writes in. For Icelandic, write natural fluent Icelandic, not machine-translated.
- Stay on topic: Kling payments, subscriptions, claims, checkout. Politely redirect off-topic questions.
- If the user is non-technical, do not switch them to a code path unless they explicitly ask. Offer the no-code workaround OR suggest they contact Kling support.