Metadata-Version: 2.4
Name: toucan-payment-skills
Version: 1.0.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

# 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 (like Claude Code, Cursor, GitHub Copilot, Codex). They provide the context, templates, and step-by-step guidance an AI agent needs to integrate Toucan Payments into any 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

```
toucan-payment-skills/
├── README.md                              # Repo overview, install instructions, skill index
├── package.json                            # npm publish metadata
├── .gitignore
├── 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 other six skills are API-reference-driven (curl-first) with no equivalent 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 from npm

Use the npm package when you want project-local, reproducible skill installation. This works well for AI coding agents because the skills are installed into the current project and can be committed with the app if desired.

```bash
npm install --save-dev @toucanpayments/toucan-payment-skills
npx skills experimental_sync --agent claude-code --yes
```

Replace `claude-code` with your agent if needed:

```bash
npx skills experimental_sync --agent cursor --yes
npx skills experimental_sync --agent codex --yes
npx skills experimental_sync --agent github-copilot --yes
npx skills experimental_sync --agent promptscript --yes
```

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

> **⚠️ Not yet published.** The npm package name above (`@toucanpayments/toucan-payment-skills`, matching this repo's `package.json`) is reserved but not live yet. Until it's published, use the [Gitea install](#install-skills-for-ai-agents-from-gitea) or [manual install](#manual-installation) flow below — both work today without npm.

Do not run `npx skills add @toucanpayments/toucan-payment-skills`; the `skills` CLI treats a bare package name as a repository source. Use the npm install + sync flow above, or use the Gitea URL flow below.

### PyPI

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

```bash
pip install toucan-payment-skills
```

The package will be published at `https://pypi.org/project/toucan-payment-skills/`.

> **⚠️ Not yet published.** The PyPI package name above matches this repo's `pyproject.toml` and is reserved but not live yet. Until it's published, use the [Gitea install](#install-skills-for-ai-agents-from-gitea) or [manual install](#manual-installation) flow below — both work today without PyPI.

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

### Install Skills for AI Agents (from Gitea)

Most supported agents can install skills directly from a git URL — this works today, without waiting on the npm/PyPI publish:

```bash
npx --yes skills add https://gitea.toucanint.com/Toucan_Payments_India/tou-skills --global --yes --full-depth
```

If your project uses **PromptScript**, do not use `--global`. PromptScript skills are project-scoped only and install under `./.agents/skills/`. If you see `PromptScript: PromptScript does not support global skill installation`, the install target is wrong, not the skill repo.

Install for PromptScript from the project where PromptScript runs:

```bash
npx --yes skills add https://gitea.toucanint.com/Toucan_Payments_India/tou-skills --agent promptscript --yes --full-depth --copy
```

If you are not using PromptScript but the installer auto-detects it, target the intended agent explicitly:

```bash
npx --yes skills add https://gitea.toucanint.com/Toucan_Payments_India/tou-skills --agent github-copilot --global --yes --full-depth
```

Or install a specific skill (use `--full-depth` when installing a single skill so sibling skills are not installed alongside it):

```bash
npx --yes skills add https://gitea.toucanint.com/Toucan_Payments_India/tou-skills --skill toucan-dqr-payment --global --yes --full-depth
npx --yes skills add https://gitea.toucanint.com/Toucan_Payments_India/tou-skills --skill toucan-checkout --global --yes --full-depth
npx --yes skills add https://gitea.toucanint.com/Toucan_Payments_India/tou-skills --skill toucan-merchant-hosted-checkout --global --yes --full-depth
npx --yes skills add https://gitea.toucanint.com/Toucan_Payments_India/tou-skills --skill toucan-card-payment --global --yes --full-depth
npx --yes skills add https://gitea.toucanint.com/Toucan_Payments_India/tou-skills --skill toucan-paylink --global --yes --full-depth
```

### Install for Codex (OpenAI)

If you are installing from Codex or another sandboxed/non-login agent shell where `npx` is not on PATH, use a PATH-resolving install command:

```bash
NPX="$(command -v npx || find "$HOME/.nvm/versions/node" "$HOME/.npm-global" /opt/homebrew /usr/local -path '*/bin/npx' -type f 2>/dev/null | sort -Vr | head -n 1)" && "$NPX" --yes skills add https://gitea.toucanint.com/Toucan_Payments_India/tou-skills --global --yes --full-depth
```

### 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)/toucan-payment-skills/toucan-dqr-payment" ~/.agents/skills/toucan-dqr-payment
ln -s "$(pwd)/toucan-payment-skills/toucan-payment-status" ~/.agents/skills/toucan-payment-status

# Or copy instead of symlink
cp -r toucan-payment-skills/toucan-dqr-payment ~/.agents/skills/
cp -r toucan-payment-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 a `skills` CLI install:**

```bash
npx skills list
# or, for a --global install:
npx skills list --global
# or:
npx skills ls -g
```

For PromptScript/project installs, run `npx skills list` from the project root.

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

---

*Built by [Toucan Payments](https://pay.toucanpay.in)*
