> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinkbill.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Integrate with an AI Agent
> Hand a prompt to the agent already writing your code and let it do the integration.
If an AI coding agent is already building your project, you can have it wire Clink in rather than following the docs step by step.
Clink publishes an open-source integration skill, [clink-integ-skills](https://github.com/clinkbillcom/clink-integ-skills), containing the integration rules, an offline CLI, and prompts written for agents. Install it, send the prompt, and let the agent work.
This path suits projects where an agent is already editing your code. If you are writing it yourself, [Hosted Checkout](/build-integration) is more direct.
Both paths produce the same result — the agent just does the typing. You still have to understand and verify what it writes.
## What the agent does
* Surveys your project structure, entry points, routes, and how environment variables are injected, before deciding how to integrate
* Scans your existing pricing page or product data, generates `clink-catalog.json`, and imports it as Clink products and prices
* Writes the server-side checkout, subscription, and webhook endpoints
* Registers the webhook endpoint and syncs the signing secret into your environment
* Hands back curl examples, a start command, and verification results
## What it does not do for you
**Decide your business logic.** What you sell, how you price it, and your refund policy are yours to define.
**Prove that payments actually work.** Someone has to open the `checkoutUrl`, pay with a test card, and confirm the local order became paid and fulfillment ran. An agent saying "integration complete" is not evidence that any of that happened.
**Go to production.** The skill works in the sandbox by default; switching to production goes through [Go Live](/go-live).
## Step 1: Have the agent install the skill
The easiest way is to tell the agent directly:
```text theme={null}
Install clink-integ-skills from: https://github.com/clinkbillcom/clink-integ-skills
```
Or install it into your local skills directory yourself:
```bash theme={null}
mkdir -p ~/.codex/skills
git clone https://github.com/clinkbillcom/clink-integ-skills.git /tmp/clink-integ-skills
cp -R /tmp/clink-integ-skills ~/.codex/skills/clink-integ-skills
```
The skill needs no extra runtime dependencies — the CLI it uses is bundled inside.
The skill follows the Codex skill format and lives under `~/.codex/skills/`. If your agent does not support that format, ask it to read the GitHub repository directly instead; the skill's own prompts include that fallback.
## Step 2: Send it the prompt
Copy this whole block to the agent:
```text theme={null}
Use $clink-integ-skills to integrate ClinkBill payments into this website project.
Goal: complete a ClinkBill sandbox test payment integration as automatically as possible.
Choose the authentication path based on the environment:
- Prefer the offline CLI bundle inside this skill: `vendor/clink-integ-cli/clink-integ-cli`. Do not install `clink-integ-cli` from GitHub or npm during normal execution.
- Prefer an existing `CLINK_SECRET_KEY`, or one I provide manually, and save it to the CLI profile with `clink auth secret set --api-key env:CLINK_SECRET_KEY --env sandbox`.
- Only run `clink login` if you are on a local desktop environment, have no Secret Key already, can open a browser, and Playwright has been provisioned offline. It opens the Dashboard login page for me to complete by hand so the CLI can read or create a Secret Key.
- If you are running in a cloud IDE, low-code editor, sandbox, or any environment without a usable browser, do not block on `clink login`. Ask me to log in to the ClinkBill Dashboard myself and hand you the Secret Key, then write it only into a secure server-side environment variable, platform Secret, or local `.env`.
- In a browserless environment, ask me only for `CLINK_SECRET_KEY`. Do not ask for `CLINK_WEBHOOK_SIGNING_KEY` up front — the CLI can manage webhook endpoints with the Secret Key, so the webhook signing key should be generated and saved by your own `clink webhook endpoint ensure --save-secret` run, then written by you into the platform Secret.
Requirements:
1. Survey the project structure, start command, server entry point, route locations, environment variable mechanism, order/purchase entry points, and whether the webhook route can read the raw body — before deciding how to integrate. Also decide whether this project actually needs recurring billing and promotion codes; if it does not, do not implement the subscription or coupon APIs. If it does need subscriptions, create a recurring price, map subscription status to entitlements, and subscribe using full event names (subscription.created, subscription.trialing, subscription.activated, subscription.past_due, subscription.incomplete_expired, subscription.cancelled, subscription.updated.plan_changed, subscription.updated.plan_change_canceled, subscription.updated.renewed, subscription.updated.cancel_at_period_end_set, subscription.updated.cancel_at_period_end_revoked, invoice.open, invoice.paid, invoice.void) — never a wildcard like subscription.*.
2. If the project has no trustworthy backend, do not put `CLINK_SECRET_KEY` or the webhook signing key in frontend code, and do not let the browser call the Clink sandbox API directly.
3. You must implement or verify the checkout session server endpoint, subscription server endpoint, webhook receiving endpoint, a local start/verify procedure, curl examples, and automated tests or a smoke test.
4. If the site already has a pricing page, paid products, or subscription plans, scan them in this order — running API / pricing page DOM / hydrated JSON, then source and config, and only then ask me — generate `clink-catalog.json`, and create the Clink products and prices with `clink catalog validate/plan/import`. Do not make me copy productId or priceId by hand.
5. Every product in `clink-catalog.json` must carry exactly one image source: `imageId`, `imageUrl`, or `imageFile`. URLs go in `imageUrl`, local public/static assets go in `imageFile`, and URLs must never go in `imageId`. When running catalog commands, add `--project-root . --public-dir public` if the project has a public/static directory.
6. Real keys may only be written to local environment variables or platform Secrets — never into source, README files, frontend variables, test fixtures, or your final reply.
7. After every successful `clink webhook endpoint ensure --save-secret`, sync the latest webhook signing key into the project runtime and restart the service. For projects with a local `.env`, prefer `--sync-env-file `; otherwise webhook signature verification will fail.
8. If a public HTTPS domain is available, configure the webhook endpoint against it directly. A cloudflared tunnel is only needed for purely local `localhost` / `127.0.0.1` development.
9. Do not describe webhook endpoint management as Dashboard-only. `clink dashboard webhook ensure` is only a compatibility alias — prefer `clink webhook endpoint ensure`.
10. The webhook handler must match the local order on both `merchantReferenceId` and `sessionId`. If the two fields point to different local orders, reject, quarantine, or escalate — never rely on one field alone.
11. Clearly distinguish local mocks, signed simulated webhooks, a real sandbox checkout session, and the real webhook that follows a completed sandbox test payment.
12. If nobody has opened `checkoutUrl` and completed a sandbox test payment, do not describe "real checkout session created plus simulated webhook passed" as a completed end-to-end payment. Even when a real webhook returns 200, you must still confirm the local order is paid/completed and that credits, entitlements, shipment, download access, or other fulfillment has actually happened.
When you are done, hand back the architecture survey, the list of changed files, an explanation of new API routes and services, the environment variables and a `.env.example`, a one-command start procedure, curl examples, a summary of CLI verification results, the webhook endpoint, the tunnel or local URL, test results, and whatever steps are left for me to do by hand.
```
Partway through, the agent will ask you for a **sandbox Secret Key**. Initialize one on the **Developers** page of the [sandbox dashboard](https://uat-dashboard.clinkbill.com) — it starts with `sk_uat_`.
Give it the sandbox key only, never a production key. And do not let the agent write keys into source or commit them — the prompt above forbids this, but check for yourself too.
## Step 3: Verify it yourself
**Do not skip this.** "Integration complete" from an agent and payments actually working are different claims.
Confirm the browser cannot reach any `sk_` key or the webhook signing secret.
Open the `checkoutUrl` the agent gives you and pay in full with test card `4242 4242 4242 4242`. Without a real payment, nothing is proven.
The row in your database should be paid, and shipping, top-up, or entitlement logic should have actually run.
This is the part an agent is most likely to get wrong. Five things have to be right:
* The signature is verified against the **raw request body**, not one that was parsed and re-serialized
* `X-Clink-SignType` is checked against `SHA256`
* The business object is read from **`event.data.object`**, not `event.data`
* Events are deduplicated by `event.id`
* Orders are matched on both `merchantReferenceId` and `sessionId`
Watch the middle two especially — getting them wrong is invisible against simulated events and only surfaces on a real payment. Check each against [Hosted Checkout](/build-integration).
Before production, go through [Go Live](/go-live) line by line.
## Common situations
**The agent says it is done, but nobody paid.** That only means a Session was created. Ask it to separate "session created" from "payment succeeded" — the skill requires that distinction.
**The project has no backend.** A purely static site cannot integrate, because the Secret Key must live on a server. Have the agent add a minimal backend route or serverless function first.
**The agent asks you to paste a productId by hand.** If your site already has a pricing page, it should scan it and use `clink catalog import` rather than making you copy IDs.
## Next
Understand the code the agent wrote, especially the webhook half.
The checklist before switching to production.