Skip to main content

Integration using AI

This guide provides a set of agent skills for integrating with the Nopan stack. Optimized for AI coding agents - Claude Code, Cursor, Windsurf, VS Code + AI, ChatGPT and custom GPTs, and RAG or MCP-augmented assistants. Each skill is a single Markdown file served directly from this site.

Quick start​

  1. Pick the skill files you need from the list below, or grab them all at once: Download all skills as a zip.
  2. Drop them into your AI agent - see How to use your AI agent.
  3. Ask the agent to perform a Nopan task — examples in Example tasks.
# Option 1 - download the bundle and extract into ./skills/nopan/ (namespaced to avoid collisions with skills from other vendors).
mkdir -p skills/nopan && curl -sL https://docs.nopan.com/skills/nopan-skills.zip -o skills/nopan/nopan-skills.zip \
  && unzip -o skills/nopan/nopan-skills.zip -d skills/nopan/ && rm skills/nopan/nopan-skills.zip

# Option 2 - pull each skill individually.
mkdir -p skills/nopan && cd skills/nopan
for s in nopan-integration nopan-authentication nopan-payments nopan-webhooks nopan-testing nopan-errors; do
  curl -sO "https://docs.nopan.com/skills/$s.md"
done
Start every new session with nopan-integration

Load nopan-integration.md first - it instructs the agent to perform a Step 0 discovery pass against your codebase before writing any Nopan code, then orients on environments, the three-layer authentication stack, and which topic skill to load next.

How the skills fit Nopan to your codebase​

The entry-point skill (nopan-integration) opens with a Step 0 discovery pass before any Nopan code is written. The agent:

  1. Scans for prior payment-provider integrations - inspects dependency manifests for third-party payments SDKs, provider-named folders under payments/ / gateways/ / providers/, and webhook routes under /webhooks/*.
  2. Identifies cross-provider abstractions - a PaymentGateway / PaymentProvider interface, a strategy or factory pattern, shared payment DTOs, a unified webhook pipeline (verify → enqueue → dedupe → reconcile), a shared retry/backoff utility, a project-wide error taxonomy.
  3. Decides whether to mirror. When there is a clear cross-provider pattern - two or more providers already slotted into the same interface, or one provider plus a clearly generic abstraction - the agent implements Nopan as another conforming implementation: same folder layout, same naming, same DTOs, same webhook pipeline, same error taxonomy. When there is no such pattern, the agent falls back to Nopan's canonical examples instead of inventing project-wide abstractions on your behalf.

Each topic skill then opens with a short "Match existing patterns" reminder, so the discovery context survives even when a single skill is loaded in isolation:

Topic skill
Match-existing-patterns reminder
nopan-authentication
Reuse existing secret-storage conventions (KMS, vault paths, env-var naming) and HTTP-client wiring. The mTLS + signing requirements are non-negotiable, but the plumbing should match the repo.
nopan-payments
Implement Nopan as another implementation of the existing PaymentGateway interface. Map Nopan request/response shapes onto existing DTOs; don't introduce parallel types.
nopan-webhooks
Plug Nopan into the existing webhook pipeline - same controller shape, same queue, same dedupe store, same reconciliation step. Don't build a parallel pipeline.
nopan-errors
Translate Nopan reasonCode families into the project's existing payment-error taxonomy. Reuse the shared retry/backoff utility instead of writing a Nopan-specific one.
nopan-testing
Follow existing test conventions for other payment-provider integrations - fixture layout, mock vs integration split, CI gating. Nopan tests live alongside the existing payment tests, not in a separate suite.

When Nopan's non-negotiable requirements (mTLS, RFC-9421 request signing, response verification, Idempotency-Key) don't cleanly fit the project's shared HTTP client, the skills tell the agent to surface the conflict before forking off - not to silently bypass the abstraction or silently break Nopan's requirements.

What does it contain?​

Each skill is a self-contained Markdown file focused on a single topic, so you can load only what's relevant to the task at hand.

Skill
Best for
nopan-integration
Entry point. Step 0 codebase discovery — scan existing payment-provider integrations, identify cross-provider abstractions, decide what to mirror. Then environments, the three-layer auth model, and routing to the right topic skill.
nopan-authentication
mTLS setup, RFC-9421 request signing, OAuth client_credentials tokens, response verification.
nopan-payments
CIT and MIT lifecycles, capture / refund / cancel, idempotency, status polling.
nopan-webhooks
Receiving events, verifying signatures, deduping retries, reconciling state.
nopan-testing
Sandbox usage, Standard Mock vs Pass-Through, Postman collection.
nopan-errors
HTTP statuses, Nopan reasonCode families, retry decision matrix.

How to use your AI agent​

Claude Code / Claude Agent SDK​

There are two ways to wire the skills into Claude Code. Pick one — they aren't interchangeable.

Option A — Vendored as inline reference files. Drop the files in a Nopan-namespaced folder at the project root and reference them from CLAUDE.md. The agent reads them as context; there is no auto-discovery.

your-project/
├── skills/
│   └── nopan/
│       ├── nopan-integration.md     # entry point
│       ├── nopan-authentication.md
│       ├── nopan-payments.md
│       ├── nopan-webhooks.md
│       ├── nopan-testing.md
│       └── nopan-errors.md
├── src/
└── ...

Option B — Native Agent Skills auto-discovery (recommended). Claude Code expects one folder per skill, with the file literally named SKILL.md inside. Install with:

for s in nopan-integration nopan-authentication nopan-payments nopan-webhooks nopan-testing nopan-errors; do
  mkdir -p .claude/skills/$s
  curl -s -o .claude/skills/$s/SKILL.md "https://docs.nopan.com/skills/$s.md"
done

Use .claude/skills/ for project-scoped skills or ~/.claude/skills/ for user-scoped. The published files already include the required name and description frontmatter, and the agent picks the right topic skill from those description fields. The Claude Agent SDK loads skills via its own configuration.

Cursor​

Place the skill files under .cursor/rules/ (one .mdc per skill). The .mdc frontmatter controls activation: alwaysApply: true for always-on, a topic description for agent-requested loading, or @<rule-name> in a prompt to invoke manually. The published files ship with Claude-style name/description only — translate the frontmatter to Cursor's fields when copying.

Windsurf​

Place one Markdown rule per skill under .windsurf/rules/ (the current convention). For older Windsurf versions, concatenate the skills into a single .windsurfrules file at the workspace root.

GitHub Copilot (VS Code, JetBrains)​

Put nopan-integration.md into .github/copilot-instructions.md — Copilot Chat loads it as repository-level instructions on every request. That file is meant to stay short (GitHub recommends keeping it to ~2 pages), so place the topic skills under .github/instructions/*.instructions.md and use the applyTo frontmatter glob to attach each one to the files that need it.

ChatGPT​

Upload nopan-integration.md and any other relevant skills as file attachments in the chat. The Custom Instructions field caps at ~1,500 characters per box, so it's too small for the full set — prefer the file-upload approach.

Custom GPTs​

Paste nopan-integration.md into the GPT builder's Instructions field, and upload the remaining topic skills under Knowledge.

Anthropic API / Agent SDK​

Pass nopan-integration.md in the system parameter on each request, and enable prompt caching on the system block so the skill content isn't re-billed per call. For programmatic skill installation, the Claude Agent SDK loads skills via its own configuration.

RAG / MCP servers​

Index all six .md files as knowledge documents, or expose them as MCP resources. The topic boundary for each skill is set by its frontmatter description.

Agent instruction files (CLAUDE.md, AGENTS.md)​

If you don't want to vendor the skill files into your repo, point your agent at the hosted copies from your top-level instruction file:

For any Nopan work, fetch https://docs.nopan.com/skills/nopan-integration.md
and follow the guidance it links to.

This is an alternative to the local-install approaches above, best suited to projects where the skills shouldn't be checked into source control.

Frontmatter portability

The published files ship with Claude-compatible name and description frontmatter. Claude Code, the Claude Agent SDK, ChatGPT, Custom GPTs, and the Anthropic API consume them as-is. Cursor (.mdc with alwaysApply/globs), Windsurf, and GitHub Copilot (applyTo) expect different fields — translate the frontmatter when adapting the files to those tools.

Common pitfalls the skills handle​

Pitfall
Covered by
Building the RFC-9421 signature base incorrectly (component names not lowercased, trailing newline, port included in @authority)
nopan-authentication
EC curve / hash mismatch (P-256 paired with SHA-384, etc.)
nopan-authentication
Calling /auth/token without mTLS + a signed request
nopan-authentication
Reusing the same Idempotency-Key with a different payload (returns 409)
nopan-payments
Confusing CIT (/payments/initiate → /payments/finalize) and MIT (/payments/charge)
nopan-payments
Calling /payments/refund before the payment is settled (refund applies post-settlement; use /payments/cancel to release an authorized-but-not-captured payment instead)
nopan-payments
Retrying a 504 on a payment mutation without polling the status endpoint first to confirm whether it actually succeeded
nopan-errors
Acking webhooks before verifying the signature
nopan-webhooks
Mocks not firing (calling /mock/set after the payment was initiated)
nopan-testing

Example tasks​

Add Nopan alongside our existing payment integration

Look at how we currently integrate our existing payment provider: the PaymentGateway interface, the shared webhook pipeline, the retry utility, the error taxonomy. Add Nopan as another implementation that matches those patterns — same folder layout, same naming, same DTOs — instead of pasting the canonical example from the API docs. Then validate the new flow with Standard Mock.

Skills activated: nopan-integration (Step 0 discovery) → nopan-authentication → nopan-payments → nopan-webhooks → nopan-testing

Debug a 401 on /auth/token

I'm getting a 401 from /auth/token. Response body:
{ "error": "invalid_signature", ... }
Walk me through the Nopan-specific culprits — signature base canonicalization, EC curve/hash pairing, mTLS trust, and created timestamp skew — and tell me which one is broken.

Skills activated: nopan-authentication, nopan-errors

Implement a webhook handler

Generate an Express endpoint that receives Nopan webhooks. It should return 202 immediately, verify the signature before parsing the body, dedupe by event ID (Nopan retries up to 10× in 24h), and reconcile ambiguous states via GET /payments/{transactionId}/status.

Skills activated: nopan-webhooks, nopan-authentication, nopan-payments

Add retry logic to a refund job

Review my refund worker and apply Nopan's reasonCode retry rules: never retry 4xxx or 5xxx; back off on 429/502/504/8xxx while preserving the original Idempotency-Key; when a mutation times out with a 504, poll the status endpoint first to check whether it actually succeeded before issuing anything new.

Skills activated: nopan-errors, nopan-payments