SDK 快速開始

本指南將幫助您在幾分鐘內開始使用 Recur SDK（版本 0.4.4+）。

安裝

npm install recur-tw
# 或
yarn add recur-tw
# 或
pnpm add recur-tw

<script src="https://unpkg.com/recur-tw@latest/dist/recur.umd.js"></script>

基本使用

1. 初始化 SDK

使用 Publishable Key 初始化 SDK：

// 使用 CDN 載入後，RecurCheckout 會自動掛載到 window
const recur = RecurCheckout.init({
  publishableKey: 'pk_test_xxx', // 您的 Publishable Key
});

// React 入口匯出的是 RecurProvider 與 hooks，不是 RecurCheckout.init
import { RecurProvider, useRecur } from 'recur-tw';

function App() {
  return (
    <RecurProvider config={{ publishableKey: 'pk_test_xxx' }}>
      <PricingButton />
    </RecurProvider>
  );
}

function PricingButton() {
  const { redirectToCheckout } = useRecur();
  return (
    <button onClick={() => redirectToCheckout({
      productId: 'cmfxq8n2a0001l8yz3k5p9t7d', // 換成你的商品 ID（API 回傳的 CUID，不是 prod_ 開頭）
      successUrl: 'https://yoursite.com/success',
      cancelUrl: 'https://yoursite.com/cancel',
    })}>
      訂閱
    </button>
  );
}

React 的完整用法（useSubscribe、useProducts、useCustomer）請看 React Hooks 與 Next.js 整合。

以下第 2、3 節與「參數說明」是 Vanilla JS（CDN RecurCheckout） 的 recur.checkout() API。React SDK 沒有 mode: 'modal' | 'iframe' 參數：hosted 用 useRecur().redirectToCheckout()，modal/embedded 用 useSubscribe()，呈現方式由 RecurProvider 的 config.checkoutMode 決定。

範例裡的 prod_xxx 只是佔位符：真實的商品 ID 是 API 回傳的 CUID（例如 cmfxq8n2a0001l8yz3k5p9t7d），請換成你在後台或 fetchProducts() 拿到的 id。

2. 開啟結帳視窗

提示：customerEmail 和 customerName 都是選填。如果未預填，用戶會在結帳頁面輸入（Email 在結帳時為必填，用於寄送收據）。

// Modal 模式結帳
await recur.checkout({
  productId: 'prod_xxx',            // 產品 ID（或使用 productSlug）
  customerEmail: 'user@example.com', // 選填：預填客戶 Email
  customerName: '王小明',            // 選填：預填客戶姓名
  externalCustomerId: 'user_123',   // 選填：您系統中的用戶 ID
  mode: 'modal',                     // 'modal' 或 'iframe'
  onSuccess: (result) => {
    console.log('Checkout session 建立成功:', result);
  },
  onPaymentComplete: (result) => {
    console.log('付款完成:', result);
    alert(`訂閱成功！ID: ${result.id}`);
  },
  onError: (error) => {
    console.error('錯誤:', error.message);
  },
  onClose: () => {
    console.log('視窗已關閉');
  },
});

3. Iframe 嵌入模式

將付款表單嵌入到您的頁面中：

await recur.checkout({
  productId: 'prod_xxx',             // 產品 ID（或使用 productSlug）
  customerEmail: 'user@example.com', // 選填：預填 Email
  customerName: '王小明',             // 選填：預填姓名
  mode: 'iframe',
  container: '#payment-container',   // CSS 選擇器或 DOM 元素
  onPaymentComplete: (result) => {
    console.log('付款完成:', result);
  },
});

<div id="payment-container"></div>

參數說明

checkout() 參數

參數	類型	必填	說明
`productId`	string	✅*	產品 ID（與 productSlug 二擇一）
`productSlug`	string	✅*	產品 Slug（與 productId 二擇一）
`customerEmail`	string	❌	預填客戶 Email（結帳時必填）
`customerName`	string	❌	預填客戶姓名
`externalCustomerId`	string	❌	外部客戶 ID（連結您系統的用戶）
`mode`	string	❌	`'modal'`（預設）或 `'iframe'`
`container`	string \| HTMLElement	❌	iframe 模式的容器（mode='iframe' 時必填）
`onSuccess`	function	❌	Checkout session 建立成功時回調
`onPaymentComplete`	function	❌	付款完成時回調
`onError`	function	❌	錯誤時回調
`onClose`	function	❌	視窗關閉時回調

Hosted Checkout 模式

如果您希望將用戶導向 Recur 託管的結帳頁面：

await recur.redirectToCheckout({
  productId: 'prod_xxx',
  successUrl: 'https://yoursite.com/success?session_id={CHECKOUT_SESSION_ID}',
  cancelUrl: 'https://yoursite.com/cancel',
  customerEmail: 'user@example.com',  // 選填
  externalCustomerId: 'user_123',     // 選填
});

取得產品列表

// 取得所有產品
const { data: products } = await recur.fetchProducts();

// 或篩選特定類型
// const { data: products } = await recur.fetchProducts({ type: 'SUBSCRIPTION' });
// const { data: products } = await recur.fetchProducts({ type: 'ONE_TIME' });

products.forEach(product => {
  console.log(product.id);            // "cmfxq8n2a0001l8yz3k5p9t7d"（CUID）
  console.log(product.name);          // "Pro Plan"
  console.log(product.type);          // "SUBSCRIPTION" | "ONE_TIME" | "CREDITS" | "DONATION"
  console.log(product.price);         // 299（整數 TWD）
  console.log(product.billingPeriod); // "MONTHLY" | "YEARLY" | ...（訂閱型才有，否則 null）
  console.log(product.trialDays);     // 14 或 null
});

Web Component

最簡單的整合方式 - 不需要寫 JavaScript：

<recur-checkout
  publishable-key="pk_test_xxx"
  product-id="prod_xxx"
  success-url="/success"
  cancel-url="/cancel"
  customer-email="user@example.com"
  button-style="gradient">
  立即訂閱
</recur-checkout>

<script src="https://unpkg.com/recur-tw@latest/dist/recur.umd.js"></script>

下一步

API 參考 - 查看完整的 API 文件
Hosted Checkout - 託管結帳頁面
範例 - 查看實際範例程式碼

常見問題

如何取得 Publishable Key？

請登入 Recur 儀表板 → 設定 → 開發者 → API 金鑰。

customerEmail 和 customerName 是必填嗎？

customerEmail 和 customerName 在建立 checkout session 時都是選填的。如果未預填，用戶會在結帳頁面輸入。但 Email 在結帳時是必填的（用於寄送收據）。

支援哪些支付方式？

目前支援透過 PAYUNi 的信用卡支付，未來將支援更多支付方式。