Toucan Payments Skills

This repository contains skills for the Toucan Payments ecosystem — structured instruction sets that let an AI coding agent integrate UPI/DQR payments, hosted checkout sessions, merchant-hosted checkout backends, card payments, pay links, transaction-status checks, and merchant result callbacks correctly, without hallucinating endpoints or parameters.

It is built for merchant-side developers: the people wiring Toucan Payments into a storefront, POS, or billing backend, who want their AI coding agent to call the real Toucan API surface — not a plausible-looking guess at it.

About Toucan Payments

Toucan Payments is a payment-processing platform covering UPI QR (DQR) payments, hosted checkout sessions, card payments, and reusable payment links, with server-side transaction-status polling and a merchant-hosted result callback for reconciliation. The skills in this repository were built directly from Toucan's API documentation and cover:

• UPI QR / DQR payments — generate a dynamic QR / VPA push request via POST /api/pay/v1/process (messageType: VPA_PUSH) and confirm the SHA-512 hashAmount signature.
• Hosted checkout sessions — obtain a Location URL via POST /api/auth/getpaymentsession and navigate it in a WebView, where the customer picks their own payment method (UPI or card) inside Toucan's own hosted pages.
• Merchant-hosted checkout backends — for a merchant with their own checkout page: three composed endpoints (/api/checkout/upi, /api/checkout/card, /api/checkout/status/:invoiceNumber) that call Toucan directly, bundled with the result callback into one ready-to-run server per framework.
• Card payments — pre-tokenize card data with AES (POST /api/helper/pretokenize/aes) then submit a card authorization (POST /api/pay/v1/process, messageType: AUTH).
• Pay links — create fixed-amount, one-time-use, or customer-entered-amount payment links via POST /api/paylink/cre.
• Pay-link communication — email or text an existing pay link to a customer via POST /api/paylink/sendCommForShortUrl.
• Transaction status — poll a transaction's result via POST /api/pay/v1/checkStatus or POST /api/switchCrossReference/digitalChargeSlip.
• Merchant callbacks — receive Toucan's payment-result webhook on your own server (/api/payments/result or split /success / /failure routes).
• Orchestration — a routing/overview skill that helps an agent pick the right skill and see how the flows compose.

What are Skills?

Skills are structured instruction sets designed for AI coding agents such as Claude Code, Cursor, GitHub Copilot, Codex CLI, Gemini CLI, OpenCode, Kiro, and Antigravity. They provide the context, templates, and step-by-step guidance needed to integrate Toucan Payments into an application — without hallucinating APIs or inventing incorrect patterns.

Each skill includes:

• SKILL.md — main instruction file with integration steps and security/anti-pattern rules
• references/ — detailed API docs, flow diagrams, test data
• templates/ — ready-to-use code per framework (where applicable)
• evals/ — behavioral test cases the skill should pass

Available Skills

| Skill | Audience | Description | |-------|----------|-------------| | toucan-payment-integration | AI Agents / Orchestration | Use when a developer asks how to integrate Toucan Payments end to end, which Toucan API to call for a given task, or how the Toucan payment flow fits together as a whole. | | toucan-dqr-payment | AI Agents | Use when a developer asks to create a Toucan UPI QR/DQR payment, generate a dynamic QR code for a customer to scan and pay, push a VPA payment request, or call POST /api/pay/v1/process with messageType: VPA_PUSH. | | toucan-checkout | AI Agents | Use when a developer asks to open a hosted Toucan checkout page, obtain a payment session for a customer, call POST /api/auth/getpaymentsession, or embed a WebView-based checkout flow in their app. | | toucan-merchant-hosted-checkout | AI Agents | Use only when the merchant has explicitly stated they already have their own checkout page and want their backend wired to call Toucan directly for UPI and card, instead of Toucan's hosted WebView. | | toucan-card-payment | AI Agents | Use when a developer asks to integrate Toucan card payments, tokenize a card number with AES, call POST /api/helper/pretokenize/aes, or submit a card authorization via POST /api/pay/v1/process with messageType: AUTH. | | toucan-paylink | AI Agents | Use when a developer asks to create a Toucan payment link, generate a reusable or one-time pay link, call POST /api/paylink/cre, or set up a customer-entered-amount payment link. | | toucan-paylink-communication | AI Agents | Use when a developer asks to send a Toucan pay link to a customer, email or text a payment link, or call POST /api/paylink/sendCommForShortUrl. | | toucan-payment-status | AI Agents | Use when a developer asks to check the status of a Toucan transaction, poll a payment result, call POST /api/pay/v1/checkStatus, or call POST /api/switchCrossReference/digitalChargeSlip. | | toucan-merchant-callback | AI Agents | Use when a developer asks to build the merchant endpoint that receives Toucan's payment result, implement /api/payments/result, /api/payments/success, or /api/payments/failure. |

Repository Structure

tou-skills/
├── README.md                              # Repo overview, install instructions, skill index
├── package.json                            # npm package metadata (CLI + skill content, name @toucanpayments/toucan-payment-skills)
├── pyproject.toml / MANIFEST.in            # PyPI package metadata (skill content only, name toucan-payment-skills)
├── .gitignore
├── cli/                                    # Cross-agent installer CLI — canonical skills below are its source of truth
│   ├── index.js                            # Entry point (add / update / doctor / list-frameworks)
│   ├── commands/                           # One file per CLI command
│   ├── adapters/                           # One file per supported coding agent (skills path, manifest path, detect, install)
│   └── lib/                                # Shared file-copy, managed-block, and version-marker utilities
├── tests/                                  # CLI integration tests (node --test)
├── scripts/
│   └── verify-skill.sh                     # Structural compliance checker — run against any skill dir
│
├── toucan-payment-integration/             # Orchestration/overview skill — no direct API calls of its own
│   ├── SKILL.md
│   └── references/
│       ├── flow-overview.md                # DQR / pay-link / card flow diagrams end to end
│       └── skill-routing.md                # Decision table: user intent -> skill to activate
│
├── toucan-dqr-payment/                     # UPI QR / DQR payment creation
│   ├── SKILL.md
│   ├── references/{dqr-api-reference.md, dqr-flow.md, test-data.md}
│   └── evals/evals.json
│
├── toucan-checkout/                        # Hosted checkout session (getpaymentsession -> Location/WebView)
│   ├── SKILL.md
│   ├── references/{checkout-api-reference.md, test-data.md}
│   └── evals/evals.json
│
├── toucan-merchant-hosted-checkout/         # Merchant's own checkout page -> composed UPI/card/status/callback backend
│   ├── SKILL.md
│   ├── references/{flow.md, api-reference.md, test-data.md}
│   ├── templates/{express/, nextjs/, flask/}
│   └── evals/evals.json
│
├── toucan-payment-status/                  # Transaction status polling / reconciliation
│   ├── SKILL.md
│   ├── references/{status-api-reference.md, test-data.md}
│   └── evals/evals.json
│
├── toucan-merchant-callback/               # Receiving side — merchant result webhook (see Known Gaps)
│   ├── SKILL.md
│   ├── references/{callback-api-reference.md, test-data.md}
│   ├── templates/{express/payments-result.js, nextjs/route.ts, python/flask_server.py}
│   └── evals/evals.json
│
├── toucan-paylink/                         # Pay link creation
│   ├── SKILL.md
│   ├── references/{paylink-api-reference.md, test-data.md}
│   └── evals/evals.json
│
├── toucan-paylink-communication/           # Send an existing pay link to a customer
│   ├── SKILL.md
│   ├── references/{send-comm-api-reference.md, test-data.md}
│   └── evals/evals.json
│
└── toucan-card-payment/                    # AES card tokenization + card authorization
    ├── SKILL.md
    ├── references/{aes-encryption-flow.md, card-payment-api-reference.md, test-data.md}
    └── evals/evals.json

Known Gaps

A few things aren't covered by the API documentation itself, so keep these in mind when integrating:

• Auth/token endpoint. Every skill requires a TOUCAN_ACCESS_TOKEN Bearer token. The token is obtained during merchant onboarding — there is no token-issuance or refresh endpoint documented here. Do not invent an OAuth flow or token endpoint; get the token from your Toucan integration contact.
• No full error-code table. The documented success values (e.g. actionCode: "00", authorizationResponseCode: "00") are covered in the reference docs, but there is no complete table of error/status codes with plain-English meaning and retryability guidance.
• No sandbox magic values. There are no documented sandbox-only trigger values (amounts, card numbers, or VPAs that deterministically force success, pending, or failure). Each skill's test-data.md notes this rather than fabricating a simulation-rules table.
• API hosts differ by endpoint. Toucan uses different base hosts per endpoint — pay.toucanpay.in (DQR, checkStatus), pay.testtoucanpay.in (card payment, checkout, digitalChargeSlip), and merchant.testtoucanpay.in (pay-link creation, checkout's murl). Each skill documents the host its own endpoints use; don't assume a test-prefixed variant works for an endpoint that only documents the non-prefixed host, or vice versa.
• toucan-checkout uses a separate credential pair. Instead of TOUCAN_ACCESS_TOKEN, it requires TOUCAN_TERMINAL_ID/TOUCAN_MERCHANT_TOKEN (sent as body fields t/mac). Your TOUCAN_ACCESS_TOKEN value also works as mac.
• toucan-merchant-callback contract is still evolving. Verify field requirements with Toucan in UAT before this endpoint handles production traffic.
• No starter templates for most calling-side skills. toucan-merchant-callback and toucan-merchant-hosted-checkout ship ready-to-use Express/Next.js/Flask server templates; the remaining skills are API-reference-driven (curl-first) rather than shipping framework-specific starter code for embedding the checkout WebView, rendering a DQR QR image, or calling AES pretokenize from a specific framework. Agents generate this code from the SKILL.md instructions directly rather than copying a template — functionally complete, just less copy-paste-ready.
• toucan-merchant-hosted-checkout only activates on an explicit signal. It composes toucan-dqr-payment, toucan-card-payment, toucan-payment-status, and toucan-merchant-callback, but only when the user has explicitly said the merchant already has their own checkout page — a generic "integrate UPI and card payments" request should route through toucan-payment-integration instead, not default here.

Confirm all of the above with your Toucan integration contact before depending on them in production code.

How to Use

Recommended: Install with the Toucan CLI (from npm)

@toucanpayments/toucan-payment-skills is a single npm package containing both the CLI installer and the canonical skill content above (the same 9 directories, unmodified). It copies the relevant skill directories into your AI coding agent's native skills path and inserts a small Toucan-managed section into that agent's instruction/manifest file (CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md, ...), without touching any unrelated content already there. Installs are idempotent — running it again just confirms everything is current.

Install in one command

From your project root, run:

npx @toucanpayments/toucan-payment-skills add skills

This auto-detects installed supported coding agents and installs the Toucan skills for them.

Install as a project dependency

If you want to keep the Toucan Payments skills package in your project's devDependencies:

npm install --save-dev @toucanpayments/toucan-payment-skills

Then run:

npx toucan-payment-skills add skills

Install for a specific coding agent

To target one framework explicitly:

npx @toucanpayments/toucan-payment-skills add skills --framework claude-code

Replace claude-code with any supported framework ID:

claude-code
cursor
github-copilot
codex-cli
gemini-cli
opencode
kiro
antigravity

Install for every supported framework

To install into every supported framework regardless of detection:

npx @toucanpayments/toucan-payment-skills add skills --all

Useful command variations

Refresh an existing installation after a skill content update:

npx @toucanpayments/toucan-payment-skills update

Check installation health (missing files, stale/legacy version, manifest not integrated):

npx @toucanpayments/toucan-payment-skills doctor

See every supported framework and its exact install paths:

npx @toucanpayments/toucan-payment-skills list-frameworks

Every add skills/update command also supports --path <dir> (target a different project) and --dry-run (preview writes without changing anything).

The npm package is published at https://www.npmjs.com/package/@toucanpayments/toucan-payment-skills.

Supported Coding Agents & Installation Paths

| Framework ID | Coding Agent | Skills Path | Manifest Path | |---|---|---|---| | claude-code | Claude Code | .claude/skills/<skill-name>/ | CLAUDE.md | | cursor | Cursor | .cursor/skills/<skill-name>/ | .cursor/rules/toucan-payment-skills.mdc | | github-copilot | VS Code Copilot | .github/skills/<skill-name>/ | .github/copilot-instructions.md | | codex-cli | OpenAI Codex CLI | .agents/skills/<skill-name>/ | AGENTS.md | | gemini-cli | Gemini CLI | .gemini/skills/<skill-name>/ | GEMINI.md | | opencode | OpenCode | .opencode/skills/<skill-name>/ | AGENTS.md | | kiro | Kiro | .kiro/skills/<skill-name>/ | .kiro/steering/toucan-payment-skills.md | | antigravity | Antigravity | .agents/skills/<skill-name>/ | .agents/rules/toucan-payment-skills.md |

ℹ️ Supported aliases
The CLI also recognizes the aliases claude, copilot, github-copilot, vscode-copilot, github-copilot-cli, codex, gemini, kiro-ide, and kiro-cli.

PyPI

For Python-first agent tooling, the same skill content is packaged for PyPI:

pip install toucan-payment-skills

The PyPI package is published at https://pypi.org/project/toucan-payment-skills/.

The PyPI package is a separate, Python-only distribution of the same skill content for programmatic/Python-side agent tooling. It has no CLI of its own and is unaffected by the npm CLI package described above.

Ask Your Agent

After installation, ask your AI coding agent one of these:

Use the toucan-dqr-payment skill to create a UPI QR payment for ₹250 for terminal
<TERMINAL_NUMBER>. Use SANDBOX configuration, compute the hashAmount as documented,
and reconcile the result via the toucan-payment-status skill.

Use the toucan-paylink skill to create a one-time-use pay link for ₹1,000 for merchant
<MERCHANT_NUMBER> / terminal <TERMINAL_NUMBER>, then use the toucan-paylink-communication
skill to email it to [email protected]. Use SANDBOX configuration.

Use the toucan-card-payment skill to tokenize a test card with AES and submit a card
authorization for ₹499 (major units, not paise) for terminal <TERMINAL_NUMBER>. Use
SANDBOX configuration and confirm cardKeyIndex matches the AES response's key_index
before sending the payment request.

Use the toucan-checkout skill to open a hosted checkout session for ₹23 (major units) for
terminal <TERMINAL_NUMBER>. Build the form-urlencoded request as documented, treat both a 302
(navigate to Location) and a 200 (no redirect needed) as success, and navigate to Location in
a WebView when present — do not call toucan-dqr-payment or toucan-card-payment yourself for
the customer's in-WebView payment-method choice.

Use the toucan-merchant-callback skill to build the server endpoint that receives Toucan's
payment result. Flag anywhere the implementation needs UAT verification before it handles
production traffic.

We already have our own checkout page at /checkout — use the toucan-merchant-hosted-checkout
skill to build the Express backend it calls: a UPI endpoint, a card endpoint, a status-poll
endpoint, and the result callback, all sharing one order record keyed by invoiceNumber.

Credential Prerequisites (Required)

Skills provide agent instructions, API references, and (where applicable) starter templates. They do not create Toucan merchant accounts or issue credentials.

Before asking your agent to use any skill, obtain the following from your Toucan onboarding contact and set them as environment variables (never hardcode them, and never commit them):

| Variable | Used by | |---|---| | TOUCAN_ACCESS_TOKEN | toucan-dqr-payment, toucan-card-payment, toucan-paylink, toucan-paylink-communication, toucan-payment-status, toucan-merchant-hosted-checkout | | TOUCAN_MERCHANT_NUMBER | toucan-dqr-payment, toucan-card-payment, toucan-paylink, toucan-paylink-communication, toucan-merchant-hosted-checkout | | TOUCAN_TERMINAL_NUMBER | toucan-dqr-payment, toucan-card-payment, toucan-paylink, toucan-payment-status, toucan-merchant-hosted-checkout | | TOUCAN_TERMINAL_MODEL_KEY / TOUCAN_MERCHANT_MODEL_KEY | toucan-paylink | | TOUCAN_TERMINAL_ID / TOUCAN_MERCHANT_TOKEN | toucan-checkout only — a separate credential pair, see Known Gaps |

As noted in Known Gaps, TOUCAN_ACCESS_TOKEN issuance and refresh happens through Toucan onboarding, not through any of these skills.

Local Installation (from a clone)

You can also run the CLI directly from a clone of this repository for local development or testing.

git clone https://gitea.toucanint.com/Toucan_Payments_India/tou-skills.git
cd tou-skills

# From inside another project you want skills installed into:
node /path/to/tou-skills/cli/index.js add skills --path /path/to/your/project --framework claude-code

Or expose it as a global toucan-payment-skills command with npm link:

cd tou-skills
npm link
cd /path/to/your/project
toucan-payment-skills add skills
toucan-payment-skills doctor
toucan-payment-skills list-frameworks

All the flags described above (--framework, --all, --path, --dry-run) work identically whether run from a clone, via npm link, or via npx @toucanpayments/toucan-payment-skills.

Manual Installation

Clone this repository (or copy the skill directories you need) into your AI agent's skills path:

git clone https://gitea.toucanint.com/Toucan_Payments_India/tou-skills.git
mkdir -p ~/.agents/skills

# Symlink (recommended — stays in sync with the clone)
ln -s "$(pwd)/tou-skills/toucan-dqr-payment" ~/.agents/skills/toucan-dqr-payment

ln -s "$(pwd)/tou-skills/toucan-payment-status" ~/.agents/skills/toucan-payment-status

# Or copy instead of symlink
cp -r tou-skills/toucan-dqr-payment ~/.agents/skills/
cp -r tou-skills/toucan-payment-status ~/.agents/skills/

Each skill directory is self-contained (SKILL.md plus its own references/, and templates//evals/ where present), so directories can be copied independently — you do not need to install all nine at once.

Verify Installation

After installing with the Toucan CLI, run doctor — it reports each framework as healthy, stale, incomplete, or not installed:

npx @toucanpayments/toucan-payment-skills doctor
# or, from a clone / npm link:
toucan-payment-skills doctor

After a manual clone/copy, run the structural verification script against any installed skill directory to confirm it matches the Skill Repository Style Guide (frontmatter shape, required sections, footer, etc.):

scripts/verify-skill.sh toucan-dqr-payment

Repeat for each skill directory you install. A FAIL line points at the specific requirement that isn't met; a WARN line is informational (e.g. toucan-payment-integration intentionally has no evals/ — it's an orchestration skill with no direct API calls).

For AI Applications

Point your AI coding agent at this repository and ask it to "integrate Toucan Payments" or use one of the Ask Your Agent prompts above. Each skill guides the agent through the request/response shape, credential checks, and known gaps for that specific flow — start with toucan-payment-integration if you're not sure which flow (DQR, checkout, merchant-hosted checkout, card, or pay link) fits your use case.

CLI Architecture

The 9 skill directories in this repository are the single canonical source of truth. The CLI (cli/) never duplicates or reformats their content — it only decides, per coding agent, where to copy them and how to integrate them into that agent's instruction file:

Canonical skills (this repo)
        -> Toucan CLI (cli/index.js)
                -> Framework adapter (cli/adapters/<id>.js: skillsPath, manifestPath, detect, detectInstalled, applyManifest)
                        -> Agent-specific skills directory + manifest/instruction file

Adding support for a new coding agent means adding one adapter file to cli/adapters/ (and one line in cli/adapters/index.js) — the CLI, commands, and manifest/version-marker logic are framework-agnostic and don't change.

Manifest files that are shared with unrelated user content (CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md) are updated via a Toucan-managed marker block (<!-- TOUCAN-PAYMENT-SKILLS:START:<framework-id> --> … <!-- TOUCAN-PAYMENT-SKILLS:END:<framework-id> -->); everything outside the block is preserved exactly. Files that are fully Toucan-owned (Cursor's .mdc rule, Kiro's steering file, Antigravity's rules file) are written as a single dedicated file instead, since there's no unrelated content to preserve. A .toucan-payment-skills.json marker inside each installed skills path records the installed version, which update and doctor use for change detection.

Testing

Run the CLI integration test suite (uses Node's built-in test runner, temp directories only — nothing under this repo is touched):

npm test

To test the actual publishable artifact rather than the source tree:

npm pack
mkdir /tmp/toucan-npm-test && cd /tmp/toucan-npm-test && npm init -y
npm install /path/to/tou-skills/toucanpayments-toucan-payment-skills-*.tgz
npx toucan-payment-skills add skills --framework claude-code
npx toucan-payment-skills doctor

Troubleshooting

| Problem | Fix | |---|---| | Unknown framework "<id>" | Run list-frameworks to see valid IDs and aliases. | | No coding agent detected... from add skills | Pass --framework <id> or --all explicitly. | | No installed Toucan skills were found from update | Run add skills first, or check --path points at the right project. | | Damaged Toucan managed block in ... | A TOUCAN-PAYMENT-SKILLS:START/END marker in that manifest file is missing its pair. Remove the incomplete marker by hand, then rerun. | | doctor reports Legacy | Skills were copied in manually before version tracking existed. Run add skills --framework <id> to bring it under version tracking. | | doctor reports Stale | The installed skill version doesn't match the CLI package version. Run update. |

Built by Toucan Payments