# For AI coding agents

URL: https://doc.securepayapi.com/for-ai-agents
Last updated: 2026-11-06

> A single markdown handbook that gives an AI coding assistant the complete checkout-layer contract — Payment Intents, the widget, webhooks — and the rules that decide money.

If you build your integration with an AI coding assistant — Claude Code,
Cursor, Copilot or similar — give it the **agent handbook**: one markdown file
with the complete contract of this checkout layer, written to be read by a
model.

[Open the handbook →](https://doc.securepayapi.com/agents.md)

## Why a separate file

These pages explain. The handbook instructs. It states each rule once, in
imperative form, with the exact field names, status codes, error codes and
decision tables an agent needs to write correct code — and, above all, the
rules about **uncertain outcomes** (`status: "pending"`, `pending_activation`)
and **server-side confirmation**, which a model will otherwise get wrong by
trusting the browser's success message.

It is self-contained: an agent that has only the handbook can build a correct
integration against the Payment Intents API, the JavaScript SDK or the raw
embedded widget, including recurring payments and webhooks.

## How to use it

1. Download it from [`/agents.md`](https://doc.securepayapi.com/agents.md).
2. Put it in your repository where your assistant reads project instructions,
   for example `docs/securepayapi.md`, and reference it from your `CLAUDE.md`,
   `AGENTS.md` or `.cursorrules`:

   ```markdown
   Payments: follow docs/securepayapi.md exactly. Never deviate from its
   "Invariants" section, and never mark an order paid without the server-side
   GET /api/v1/payment-intents/{id} check it describes.
   ```

3. Ask for the integration in the handbook's terms — for example "implement
   the flow from docs/securepayapi.md: the backend creates the intent, the page
   mounts the SDK in external submit mode, the backend confirms the intent
   before placing the order".
4. Review what the agent writes against the handbook's pre-launch checklist
   before going live.

## What it contains

- The credentials and identifiers, and where each may appear
- `POST /api/v1/payment-intents` — every field, limit, response and error code,
  including the `subscription` object for recurring payments
- `GET /api/v1/payment-intents/{id}` — the confirmation step and its decision table
- The JavaScript SDK: options, the handle, the result payload, external submit,
  wallets, domains
- The raw embedded-widget `postMessage` protocol
- Hosted checkout pages
- Webhooks: setup, payload, signature verification, retries, coalescing, the
  status table, subscription events
- The transaction lookup
- Sandbox, test cards and the scenarios to pass
- Retry and idempotency rules per endpoint, and a pre-launch checklist

> **Note:**
The handbook covers the checkout layer only — where card data never touches
your systems. Merchants integrating with the processing API directly (sending
card data themselves, PCI DSS scope) use the separate handbook in the
[direct-integration section](https://doc.securepayapi.com/private).

Hosted invoice [Bank Pay-ins](https://doc.securepayapi.com/bank-payins) and [USDC pay-ins](https://doc.securepayapi.com/usdc-payins) are
also linked from the handbook. They are separate from Payment Intents and SDK
payment methods; merchant setup uses the private direct-integration contract.