For AI coding agents

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 →

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

Download it from /agents.md.

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.

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".
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.

Hosted invoice Bank Pay-ins and USDC pay-ins are also linked from the handbook. They are separate from Payment Intents and SDK payment methods; merchant setup uses the private direct-integration contract.