Recur Quickstart

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

Step 1: Install SDK

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:

RECUR_PUBLISHABLE_KEY=pk_test_xxx
RECUR_SECRET_KEY=sk_test_xxx

Step 3: Add Provider (React)

Wrap your app with RecurProvider:

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

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

recur-quickstart

SKILL.md