# Recur Quickstart

> Quick setup guide for Recur payment integration. Use when starting a new Recur integration, setting up API keys, installing the SDK, or when user mentions "integrate Recur", "setup Recur", "Recur 串接", "金流設定".

- Skill: `recur-tw/recur-quickstart` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add recur-tw/recur-quickstart`
- Raw SKILL.md: https://api.skillmd.com/api/skills/recur-tw/recur-quickstart/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: MIT
- Author: recur-tw (https://skillmd.com/u/recur-tw)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/recur-tw/recur-quickstart

---


# Recur Quickstart

You are helping a developer integrate Recur, Taiwan's subscription payment platform (similar to Stripe Billing).

## Step 1: Install SDK

```bash
pnpm add recur-tw
# or
npm install recur-tw
```

## Step 2: Get API Keys

API keys are available in the Recur dashboard at `app.recur.tw` → Settings → Developers.

**Key formats:**
- `pk_test_xxx` - Publishable key (frontend, safe to expose)
- `sk_test_xxx` - Secret key (backend only, never expose)
- `pk_live_xxx` / `sk_live_xxx` - Production keys

**Environment variables to set:**
```bash
RECUR_PUBLISHABLE_KEY=pk_test_xxx
RECUR_SECRET_KEY=sk_test_xxx
```

## Step 3: Add Provider (React)

Wrap your app with `RecurProvider`:

```tsx
import { RecurProvider } from 'recur-tw'

export default function App({ children }) {
  return (
    <RecurProvider
      config={{
        publishableKey: process.env.NEXT_PUBLIC_RECUR_PUBLISHABLE_KEY,
      }}
    >
      {children}
    </RecurProvider>
  )
}
```

## Step 4: Create Your First Checkout

```tsx
import { useRecur } from 'recur-tw'

function PricingButton({ productId }: { productId: string }) {
  const { checkout } = useRecur()

  const handleCheckout = async () => {
    await checkout({
      productId,
      onPaymentComplete: (subscription) => {
        console.log('Payment successful!', subscription)
      },
      onPaymentFailed: (error) => {
        console.error('Payment failed:', error)
      },
    })
  }

  return <button onClick={handleCheckout}>Subscribe</button>
}
```

## Step 5: Set Up Webhooks

Create a webhook endpoint to receive payment notifications. See the `recur-webhooks` skill for detailed instructions.

## Quick Verification Checklist

- [ ] SDK installed (`pnpm list recur-tw`)
- [ ] Environment variables set
- [ ] RecurProvider wrapping app
- [ ] Test checkout works in sandbox
- [ ] Webhook endpoint configured

## Common Issues

### "Invalid API key"
- Check key format: must start with `pk_test_`, `sk_test_`, `pk_live_`, or `sk_live_`
- Ensure using publishable key for frontend, secret key for backend

### "Product not found"
- Verify product exists in Recur dashboard
- Check you're using correct environment (sandbox vs production)

### Checkout not appearing
- Ensure `RecurProvider` wraps your app
- Check browser console for errors
- Verify publishable key is correct

## Next Steps

- `/recur-checkout` - Learn checkout flow options
- `/recur-webhooks` - Set up payment notifications
- `/recur-entitlements` - Implement access control

## Resources

- [Recur Documentation](https://recur.tw/docs)
- [SDK on npm](https://www.npmjs.com/package/recur-tw)
- [API Reference](https://recur.tw/docs/api)