# Build with AI
Source: https://docs.zahlo.eu/ai

Zahlo's documentation is written to be read by coding agents. Give your agent the docs and a test-mode key, and it can build a working integration.

## Files for agents

- [`/llms.txt`](https://docs.zahlo.eu/llms.txt): an index of every page with a one-line description. Start here.
- [`/llms-full.txt`](https://docs.zahlo.eu/llms-full.txt): every page in one file, for agents that read everything up front.
- [`/openapi.json`](https://docs.zahlo.eu/openapi.json): the API contract as an OpenAPI 3 spec, for generating clients or checking request and response shapes.
- Each written page as Markdown (endpoint pages excepted, the spec covers them): add `.md` to its URL, for example [`/quickstart.md`](https://docs.zahlo.eu/quickstart.md).

## Copy-paste prompt

Put your test-mode secret key (it starts with `zk_test_`) in the environment variable `ZAHLO_API_KEY`, then give your agent this prompt, filling in the brackets:

```text
Integrate Zahlo payments into this project.
Read https://docs.zahlo.eu/llms.txt first, then open "Choose your integration"
and follow exactly the one quickstart that matches: business = [e-commerce | SaaS],
checkout = [hosted | embedded | payment link], platform = [Next.js | plain website with PHP or Node | WooCommerce].
The test-mode secret key is in the ZAHLO_API_KEY environment variable; never print it, commit it or send it to the browser.
Follow every rule on https://docs.zahlo.eu/ai. If what I ask for is listed on
https://docs.zahlo.eu/unsupported, tell me and offer the workaround instead of building it.
When done, tell me how to make a test payment with a test card and what I should see.
```

## Rules for generated integrations

1. **The secret key stays on the server.** Read it from `ZAHLO_API_KEY`. The browser only ever gets a session's `url` (hosted) or its `clientToken` (embedded).
2. **Verify every webhook** on the raw request body before parsing it, and reject a bad signature or a timestamp more than 300 seconds old with `400`.
3. **Dedupe and act in one transaction.** Insert the event id into a table with a unique constraint and apply the business change (mark the order paid, grant access) in the same database transaction; return `2xx` only after it commits. A duplicate event id returns `200` without work. Never record the event id, return `200`, and fulfil afterwards: a crash in between loses the order.
4. **Tolerate out-of-order events.** Re-fetch the object (`GET /checkout-sessions/:id`, `GET /subscriptions/:id`) and act on its current state instead of applying an older event's data.
5. **Fulfil one-time orders on `checkout.session.completed`**, never on `payment.confirmed` alone and never because the customer reached your success page. The success page shows "processing" until the webhook has run.
6. **Grant SaaS access from the subscription's status**: active while `trialing` or `active`, or `past_due` within the grace period.
7. **Handle reversals**: `refund.succeeded`, `dispute.created`, `subscription.payment_failed`, `subscription.past_due` and `subscription.cancelled`.
8. **Retry safely.** Send one `Idempotency-Key` per logical operation and reuse it on every retry. Retry only on a network error, `409 request_in_progress`, `429` or a `5xx` (including `provider_outcome_unknown`), at most twice, honouring `Retry-After`. Never retry other `4xx`, and never retry with a new key.
9. **Never hard-code object ids.** The Test mode and live are separate accounts with different ids. Find prices with `GET /prices?lookupKey=…` and coupons by their code, and create customers at runtime. Treat every id as an opaque string.
10. **Register your checkout domains** (`POST /checkout-domains`) before testing; in test mode this includes `localhost:<port>`.
11. **Use `{CHECKOUT_SESSION_ID}`** in `successUrl` so your success page can retrieve the session with the secret key.
12. **Check [Not supported](/unsupported) and [Limits](/limits)** before promising a feature.
