---
title: 5 分鐘快速開始
description: 從零開始建立您的第一個 Recur 結帳流程
---

# 5 分鐘快速開始

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

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

## 步驟 1：取得 API Key

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

  **重要**：Secret Key 應只在後端使用，切勿暴露在前端代碼中。

## 步驟 2：建立商品

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

## 步驟 3：建立 Checkout Session

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

```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 };
```

```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']
```

```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"
  }'
```

## 步驟 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：處理結帳結果

### 成功頁面

用戶完成付款後，會被導向 `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](/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-reference) - 完整 API 文件