# 5 分鐘快速開始 (/getting-started/quick-start)





5 分鐘快速開始 [#5-分鐘快速開始]

本指南將帶您完成最簡單的整合方式：**Hosted Checkout**。

<Callout type="info">
  **Hosted Checkout** 是最快的整合方式，只需後端呼叫一個 API，即可將用戶導向 Recur 託管的結帳頁面。
</Callout>

步驟 1：取得 API Key [#步驟-1取得-api-key]

1. 登入 [Recur 後台](https://app.recur.tw)
2. 前往 **設定 → 開發者 → API 金鑰**
3. 複製 **Secret Key**（`sk_test_xxx`）

<Callout type="warning">
  **重要**：Secret Key 應只在後端使用，切勿暴露在前端代碼中。
</Callout>

步驟 2：建立商品 [#步驟-2建立商品]

1. 前往 **商品管理 → 新增商品**
2. 填寫商品名稱和價格
3. 儲存後複製 **商品 ID**（`prod_xxx`）

步驟 3：建立 Checkout Session [#步驟-3建立-checkout-session]

在您的後端呼叫 API 建立 Checkout Session：

<Tabs items="['Node.js', 'Python', 'cURL']">
  <Tab value="Node.js">
    ```typescript
    // pages/api/checkout.ts (Next.js) 或您的後端 API
    const response = await fetch('https://api.recur.tw/v1/checkout/sessions', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer sk_test_xxx', // 替換成您的 Secret Key
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        productId: 'prod_xxx',           // 替換成您的商品 ID
        mode: 'SUBSCRIPTION',            // SUBSCRIPTION 或 PAYMENT
        successUrl: 'https://your-site.com/success?session_id={CHECKOUT_SESSION_ID}',
        cancelUrl: 'https://your-site.com/cancel',
      }),
    });

    const { id, url, expiresAt } = await response.json();

    // 回傳 URL 給前端
    return { checkoutUrl: url };
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.post(
        'https://api.recur.tw/v1/checkout/sessions',
        headers={
            'Authorization': 'Bearer sk_test_xxx',  # 替換成您的 Secret Key
            'Content-Type': 'application/json',
        },
        json={
            'productId': 'prod_xxx',        # 替換成您的商品 ID
            'mode': 'SUBSCRIPTION',
            'successUrl': 'https://your-site.com/success?session_id={CHECKOUT_SESSION_ID}',
            'cancelUrl': 'https://your-site.com/cancel',
        }
    )

    data = response.json()
    checkout_url = data['url']
    ```
  </Tab>

  <Tab value="cURL">
    ```bash
    curl -X POST https://api.recur.tw/v1/checkout/sessions \
      -H "Authorization: Bearer sk_test_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "productId": "prod_xxx",
        "mode": "SUBSCRIPTION",
        "successUrl": "https://your-site.com/success?session_id={CHECKOUT_SESSION_ID}",
        "cancelUrl": "https://your-site.com/cancel"
      }'
    ```
  </Tab>
</Tabs>

步驟 4：導向結帳頁面 [#步驟-4導向結帳頁面]

在前端將用戶導向返回的 `url`：

```typescript
// 前端 JavaScript
async function handleCheckout() {
  const response = await fetch('/api/checkout', { method: 'POST' });
  const { checkoutUrl } = await response.json();

  // 導向 Recur 結帳頁面
  window.location.href = checkoutUrl;
}
```

步驟 5：處理結帳結果 [#步驟-5處理結帳結果]

成功頁面 [#成功頁面]

用戶完成付款後，會被導向 `successUrl`。您可以使用 URL 中的 `session_id` 查詢訂單狀態：

```typescript
// pages/success.tsx
export default function SuccessPage() {
  const searchParams = useSearchParams();
  const sessionId = searchParams.get('session_id');

  // 可選：呼叫後端 API 驗證 session 狀態

  return <h1>感謝您的訂閱！</h1>;
}
```

設定 Webhook（建議） [#設定-webhook建議]

為了確保不遺漏任何付款通知，建議設定 [Webhook](/guides/webhooks)。

完整範例 [#完整範例]

以下是一個完整的 Next.js 範例：

```typescript
// app/api/create-checkout/route.ts
import { NextResponse } from 'next/server';

export async function POST() {
  const response = await fetch('https://api.recur.tw/v1/checkout/sessions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.RECUR_SECRET_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      productId: process.env.RECUR_PRODUCT_ID,
      mode: 'SUBSCRIPTION',
      successUrl: `${process.env.NEXT_PUBLIC_URL}/success?session_id={CHECKOUT_SESSION_ID}`,
      cancelUrl: `${process.env.NEXT_PUBLIC_URL}/pricing`,
    }),
  });

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data.error }, { status: response.status });
  }

  return NextResponse.json({ url: data.url });
}
```

```typescript
// app/pricing/page.tsx
'use client';

export default function PricingPage() {
  const handleSubscribe = async () => {
    const response = await fetch('/api/create-checkout', { method: 'POST' });
    const { url } = await response.json();
    window.location.href = url;
  };

  return (
    <button onClick={handleSubscribe}>
      立即訂閱
    </button>
  );
}
```

下一步 [#下一步]

* [API 認證](/getting-started/authentication) - 深入了解認證方式
* [Webhook 整合](/guides/webhooks) - 接收即時付款通知
* [API Reference](/api) - 完整 API 文件