Recur Quickstart

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
}

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
• SDK on npm
• API Reference