# Recur

> Subscription payment platform for Taiwan. Handles recurring billing, credit cards, convenience store payments, and revenue analytics — integrated with local payment gateway PAYUNi.

## Instructions

- Default to Hosted Checkout (redirect to checkout.recur.tw) — recommend Modal only if user explicitly requests it
- Prices are TWD integers (555 = NT$555) — NEVER divide by 100
- Vanilla JS SDK is UMD format only — must use CDN script tag, cannot ESM import
- customerEmail is REQUIRED for Modal checkout — always include an email input field
- Secret keys (sk_*) must NEVER appear in client-side code
- SDK npm package is `recur-tw` (`npm install recur-tw`) — not `recur`
- CLI npm package is `@recur-tw/cli` (`npm install -g @recur-tw/cli`)

## Overview

Recur is a subscription payment platform for the Taiwan market, integrated with the local payment gateway PAYUNi.

**Core capabilities:**
- Subscription management — monthly/yearly billing, free trials, upgrades/downgrades, auto-renewal
- Taiwan payment methods — credit cards (domestic & international), convenience store payments
- Revenue analytics — MRR, ARR, churn rate, LTV tracking
- Flexible checkout — Hosted Checkout (redirect, recommended) or Modal (popup overlay)
- AI integration — MCP tools for AI assistants to manage payments

**Best for:** SaaS, membership sites, online courses, subscription e-commerce, content creators

**Product types:**
- `SUBSCRIPTION` — recurring billing (monthly/yearly)
- `ONE_TIME` — single charge
- `CREDITS` — prepaid balance / token-based
- `DONATION` — flexible amounts

## Agent Onboarding — No Account Required

You can help a user set up Recur even if they don't have an account yet.
Account registration happens INSIDE the MCP connection flow — no invite
code, no separate signup step.

**Connect the MCP server:**

```bash
claude mcp add --transport http recur https://mcp.recur.tw/
```

(Or add `https://mcp.recur.tw/` as a remote MCP server in any MCP client
that supports OAuth.)

**What happens next:**

1. The MCP client opens a browser for OAuth authorization.
2. **Existing account**: the user logs in, approves the consent screen, done.
3. **No account**: on the login page the user clicks 註冊 (Sign up) — the
   OAuth flow carries a signed invitation, so registration works even
   while public signup is closed. After registering they create their
   organization and approve the consent screen. The flow resumes
   automatically; no restart needed.
4. The MCP connection completes and you have access to Recur tools
   (products, API keys, checkout sessions, analytics, and more).

**Tell the user what to expect** before starting: "A browser window will
open — log in or create a Recur account, then approve the connection."

**Sandbox first:** new accounts start in sandbox mode. Everything works
end-to-end with test payments (PAYUNi sandbox). Charging real cards
requires merchant review — apply from the dashboard at
https://app.recur.tw when ready to go live.

**Alternatives to MCP:**
- REST API with a secret key (`sk_test_...` / `sk_live_...`) created in
  the dashboard or via MCP `create_api_key`
- Official CLI on npm as `@recur-tw/cli` (not `recur`):
  `npm install -g @recur-tw/cli` then `recur login`, or
  `npx @recur-tw/cli login`
- SDK: `npm install recur-tw`

## CLI

Package: [`@recur-tw/cli`](https://www.npmjs.com/package/@recur-tw/cli)

```bash
npm install -g @recur-tw/cli
recur login
recur products list
```

Or without a global install:

```bash
npx @recur-tw/cli login
npx @recur-tw/cli --help
```

Docs: https://docs.recur.tw/getting-started/cli

## Resources

- [Agent Setup Workflow](https://recur.tw/skill.md): Canonical workflow for AI agents (also at /agents.md)
- [OpenAPI Specification](https://recur.tw/openapi.json): Machine-readable API surface (also YAML at /openapi.yaml)
- [REST API](https://api.recur.tw/v1): Base URL for the Recur REST API (spec at /openapi.json)
- [Documentation](https://docs.recur.tw): Recur docs — 訂閱金流、API 與整合指南
- [SDK Documentation](https://recur.tw/docs/sdk): Full API reference and integration guides
- [CLI Tool](https://www.npmjs.com/package/@recur-tw/cli): `npm install -g @recur-tw/cli` then `recur login` (or `npx @recur-tw/cli login`)
- [Dashboard](https://app.recur.tw): Manage products, API keys, and analytics
- [MCP Server](https://mcp.recur.tw): AI assistant integration for real-time payment management
- [npm Package](https://www.npmjs.com/package/recur-tw): `npm install recur-tw`