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 (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	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

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.

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

Replace claude-code with your agent if needed:

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 or manual install 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:

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 or manual install flow below — both work today without PyPI.

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 customer@example.com. 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.

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:

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:

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:

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):

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:

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:

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:

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

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.

---

Built by Toucan Payments