# Build with an AI assistant

> Point Claude, Cursor, Copilot or any AI coding assistant at these docs, and give it the rules a Devzity integration must follow.

These docs are written to be read by AI coding assistants as well as people. Give your assistant the Markdown below, then the rules, and it can build a correct integration.

## Give your assistant the docs

| What | Address |
| --- | --- |
| Index of every page (the `llms.txt` standard) | `https://docs.devzity.com/llms.txt` |
| Every page in one file | `https://docs.devzity.com/llms-full.txt` |
| One page as Markdown | `https://docs.devzity.com/v1/<page>.md`, for example `https://docs.devzity.com/v1/webhooks.md` |
| The API as OpenAPI 3 | `https://docs.devzity.com/openapi/devzity-v1.yaml` |

- **Claude Code, Cursor, Windsurf:** paste the `llms-full.txt` address into the chat, or add it as a docs source, and ask it to read it before writing code.
- **ChatGPT, Gemini, Copilot Chat:** paste the Markdown of the pages you need ([Quickstart](https://docs.devzity.com/v1/quickstart.md), [Webhooks](https://docs.devzity.com/v1/webhooks.md), your platform page).
- **Code generators:** generate a client from the OpenAPI document, or use the official SDK from the [Quickstart](https://docs.devzity.com/v1/quickstart.md).

## The rules: paste these into your assistant

Put this block in your project's assistant instructions (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, or Copilot's custom instructions). Each rule links to the page that explains it.

```text
Devzity integration rules (docs: https://docs.devzity.com/llms.txt)

1. The secret key (dz_test_sk_… / dz_live_sk_…) lives only on the server, read from an
   environment variable. Never put it in a browser, mobile app, repository or log.
2. Create payments only from the server: POST https://api.devzity.com/v1/payments (or the SDK),
   with an Idempotency-Key header that is unique per order attempt and reused on retry.
3. Amounts are taka as a decimal string with at most two decimals ("500.00").
   Never compute money with floating point.
4. Send the customer to the payment's checkout_url. Do not build your own bKash/Nagad
   payment screen; the customer never types a transaction ID.
5. Never mark an order paid because the customer returned to return_url, or because the
   app or browser said so. devzity_status on the return URL is a hint, not proof.
6. Fulfil an order only after a verified payment.paid webhook, or after the server reads
   GET https://api.devzity.com/v1/payments/{id} and sees status PAID.
7. Verify every webhook: HMAC-SHA256 over "<t>." + the raw request body with the
   endpoint's whsec_ secret, compared in constant time, rejecting a t older than 5 minutes.
   Read the raw bytes; never re-serialize the JSON before verifying.
8. Webhooks arrive at least once and in any order. Store each event id and skip one you
   have already handled. Ignore event types you don't know.
9. Answer the webhook with a 2xx quickly; do slow work afterwards.
10. Build and test everything with a dz_test_sk_ key and a Test webhook endpoint first.
    Switch to live keys only after the Going live checklist.
11. Keep the order <-> payment link with merchant_reference or external_id, and keep your
    own record of what was paid; never trust amounts sent back by the client.
12. Handle errors by their code (see Errors), retry only what is safe to retry, and keep
    the same Idempotency-Key when you do.
13. Use the REST API directly unless the Quickstart shows a real install command for an SDK.
    An SDK marked "preview" is not on npm/Maven yet; do not invent package names or versions.
```

## Ask your assistant to check its work

After it writes the integration, ask it to confirm each item, then run the [Testing](https://docs.devzity.com/v1/testing.md) flow yourself:

- [ ] No secret key anywhere outside server environment variables.
- [ ] `POST /v1/payments` sends an `Idempotency-Key`.
- [ ] The webhook handler verifies `Devzity-Signature` on the raw body and rejects old timestamps.
- [ ] Orders are fulfilled only from `payment.paid` (or a server-side status check), once per event id.
- [ ] The return page shows "checking payment…" and asks your server, instead of trusting the URL.
- [ ] A test payment completes end to end in test mode, including the webhook.

## Pages your assistant will need most

- [Quickstart](https://docs.devzity.com/v1/quickstart.md): create a payment, open the checkout, receive the webhook.
- [Authentication](https://docs.devzity.com/v1/authentication.md): keys, test and live.
- [Webhooks](https://docs.devzity.com/v1/webhooks.md): signature, retries, ordering.
- [Checkout](https://docs.devzity.com/v1/checkout.md): return URL and why it is only a hint.
- [Idempotency](https://docs.devzity.com/v1/idempotency.md) and [Errors](https://docs.devzity.com/v1/errors.md).
- [Mobile apps](https://docs.devzity.com/v1/mobile-backend.md): the app only opens the checkout URL; your backend does the rest.