# Using these docs with AI

How this site is built to be read by AI assistants and coding agents, and how to point one at it.

Source: https://developer.inoviopay.com/ai.html  
Markdown: https://developer.inoviopay.com/ai.md

## Every page is Markdown

Every HTML page on this site has a Markdown twin at the same path with a `.md` extension. The Markdown is the source; the HTML is generated from it. Both carry the same headings, tables, code samples and anchors.

| You want | Fetch |
|---|---|
| One page | `https://developer.inoviopay.com/api/sale.md` |
| The site index with one-line summaries | `https://developer.inoviopay.com/llms.txt` |
| Every page in a single file | `https://developer.inoviopay.com/llms-full.txt` |
| The API as a machine-readable spec | `https://developer.inoviopay.com/openapi.yaml` |
| Every example request, importable | `https://developer.inoviopay.com/postman.json` |

Clients that send `Accept: text/markdown` get the Markdown for an `.html` URL without changing the path. Each HTML page also declares its twin with `<link rel="alternate" type="text/markdown">`, carries `TechArticle` JSON-LD, and has a **Copy for AI** button in the header that copies the page as Markdown to your clipboard.

**curl**

```bash
curl -s -H "Accept: text/markdown" https://developer.inoviopay.com/api/sale.html
```

**Python**

```python
import urllib.request
md = urllib.request.urlopen("https://developer.inoviopay.com/api/sale.md").read().decode()
```

## Point an assistant at the site

**Claude Code, Cursor, Copilot, Windsurf and similar.** Paste the `llms.txt` URL into your project rules or a `docs` reference, or add this line to your project's `CLAUDE.md` / `.cursorrules`:

```markdown
Inovio gateway docs: https://developer.inoviopay.com/llms.txt (fetch the .md pages it lists before answering questions about the Inovio API or SDKs).
```

**ChatGPT, Claude.ai, Gemini.** Paste `https://developer.inoviopay.com/llms-full.txt` and ask your question; the full site is small enough to fit in a single context window.

**Code generation from the spec.** `openapi.yaml` is OpenAPI 3.1. The API is not REST: it is one form-encoded `POST` whose `request_action` field selects the operation, so use the spec for parameter names, enums and response fields rather than for generating a client. The SDKs are the supported clients.

## What agents should know about this API

These are the facts an assistant most often gets wrong when reasoning from generic payment-gateway knowledge. Each links to the page that proves it.

- **There is no sandbox host.** Test and production use the same URL and credentials; the portal configuration decides which merchant ID is hit. [Get started](https://developer.inoviopay.com/get-started.md)
- **A decline is a normal response, not an error.** `TRANS_STATUS_NAME=DECLINED` with `SERVICE_RESPONSE` and `PROCESSOR_RESPONSE` explaining why. The SDKs return it; they do not throw. [How the SDKs think](https://developer.inoviopay.com/sdks/concepts.md)
- **The tokenization HMAC does not include the card number.** The PDF says it does; the gateway disagrees. Sign `timestamp || unique_id || site_id` with the Site Key. [Tokenization](https://developer.inoviopay.com/api/tokenization.md)
- **A token replaces the PAN only.** You still send `pmt_expiry` and, where required, `pmt_key`. [Tokenization](https://developer.inoviopay.com/api/tokenization.md)
- **Send `CREDIT_ON_FAIL=1` on a reversal** and the gateway itself re-routes to a credit if the order has already settled. Never write a client-side "try reverse, then credit" fallback. [Reversal](https://developer.inoviopay.com/api/reversal.md)
- **`XTL_ORDER_ID` gives you idempotent retries.** A retried request with the same id returns the original result instead of charging twice. After a timeout, call `CCSTATUS` before retrying. [Order status](https://developer.inoviopay.com/api/status.md)
- **Amounts are decimal strings**, never floats. The SDKs reject `1.25` as a number and accept `"1.25"`. [How the SDKs think](https://developer.inoviopay.com/sdks/concepts.md)
- **The statement descriptor must not contain a space, underscore or slash.** The whole transaction is rejected otherwise. [Shopping cart plugins](https://developer.inoviopay.com/carts/index.md)

## Structure that makes the site easy to parse

- Stable, slugified section ids (`/api/sale.html#request-parameters`), unchanged from the previous site where they existed.
- One `h1` per page, `h2` per section, `h3` inside a section. No deeper nesting.
- Parameter tables always have the parameter in the first column with a `Required` or `Optional` badge (`(required)` / `(optional)` in the Markdown).
- Code samples are fenced with a language tag; example requests are complete and use the placeholder credentials `api_user` / `P@ssw0rd!` / site `12345`.
- `robots.txt` explicitly allows AI crawlers; `sitemap.xml` lists every page.