5 分鐘快速開始

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

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

步驟 1：取得 API Key

登入 Recur 後台
前往 設定 → 開發者 → API 金鑰
複製 Secret Key（sk_test_xxx）

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

步驟 2：建立商品

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

步驟 3：建立 Checkout Session

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

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

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

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：

// 前端 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 查詢訂單狀態：

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

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

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

設定 Webhook（建議）

為了確保不遺漏任何付款通知，建議設定 Webhook。

完整範例

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

// 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 });
}

// 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 認證 - 深入了解認證方式
Webhook 整合 - 接收即時付款通知
API Reference - 完整 API 文件

5 分鐘快速開始

On this page