Metadata-Version: 2.4
Name: toucan-payment-skills
Version: 1.1.0
Summary: Toucan Payments Skills for AI coding agents
License-Expression: MIT
Project-URL: Homepage, https://gitea.toucanint.com/Toucan_Payments_India/tou-skills#readme
Project-URL: Repository, https://gitea.toucanint.com/Toucan_Payments_India/tou-skills
Project-URL: Issues, https://gitea.toucanint.com/Toucan_Payments_India/tou-skills/issues
Keywords: skills,ai-agents,toucan-payments,payments,upi,dqr,checkout,merchant-hosted-checkout,paylink,card-payment
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Toucan Payments Skills

This repository contains **skills** for the [Toucan Payments](https://pay.toucanpay.in) 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`](./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`](./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`](./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`](./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`](./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`](./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`](./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`](./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`](./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:

```bash
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`:

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

Then run:

```bash
npx toucan-payment-skills add skills
```

### Install for a specific coding agent

To target one framework explicitly:

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

Replace `claude-code` with any supported framework ID:

```text
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:

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

### Useful command variations

Refresh an existing installation after a skill content update:

```bash
npx @toucanpayments/toucan-payment-skills update
```

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

```bash
npx @toucanpayments/toucan-payment-skills doctor
```

See every supported framework and its exact install paths:

```bash
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:

```bash
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:

```text
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.
```

```text
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 customer@example.com. Use SANDBOX configuration.
```

```text
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.
```

```text
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.
```

```text
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.
```

```text
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](#known-gaps) |

As noted in [Known Gaps](#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.

```bash
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`:

```bash
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:

```bash
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:

```bash
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.):

```bash
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](#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):

```bash
npm test
```

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

```bash
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](https://pay.toucanpay.in)*
