Hosted Checkout

Hosted Checkout 是最簡單的整合方式。您只需在後端建立 Checkout Session，然後將用戶導向 Recur 託管的結帳頁面。

適合場景：

快速上線，無需開發前端 UI
想使用 Recur 最佳化的結帳體驗
不需要完全客製化結帳頁面

運作流程

1. 用戶點擊「訂閱」按鈕
   ↓
2. 您的後端呼叫 POST /v1/checkout/sessions
   ↓
3. Recur 返回 Checkout Session URL
   ↓
4. 前端導向該 URL
   ↓
5. 用戶在 Recur 結帳頁面完成付款
   ↓
6. 重新導向回 successUrl 或 cancelUrl

建立 Checkout Session

API 端點

POST https://api.recur.tw/v1/checkout/sessions

請求參數

參數	必填	說明
`productId`	✅	商品 ID
`mode`	❌	`PAYMENT`（一次性）、`SUBSCRIPTION`（訂閱）、`SETUP`（僅儲存卡片）
`successUrl`	✅	成功後的重新導向 URL
`cancelUrl`	✅	取消時的重新導向 URL
`customerEmail`	❌	預填客戶 Email
`metadata`	❌	自訂 metadata（僅 Secret Key 可用）

程式碼範例

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

export async function POST(request: Request) {
  const body = await request.json();

  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: body.productId,
      mode: 'SUBSCRIPTION',
      successUrl: `${process.env.NEXT_PUBLIC_URL}/success?session_id={CHECKOUT_SESSION_ID}`,
      cancelUrl: `${process.env.NEXT_PUBLIC_URL}/pricing`,
      customerEmail: body.email,
      metadata: {
        userId: body.userId,
      },
    }),
  });

  const data = await response.json();

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

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

// routes/checkout.js
const express = require('express');
const router = express.Router();

router.post('/create-checkout', async (req, res) => {
  try {
    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: req.body.productId,
        mode: 'SUBSCRIPTION',
        successUrl: `${process.env.APP_URL}/success?session_id={CHECKOUT_SESSION_ID}`,
        cancelUrl: `${process.env.APP_URL}/pricing`,
      }),
    });

    const data = await response.json();

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

    res.json({ url: data.url });
  } catch (error) {
    res.status(500).json({ error: 'Internal server error' });
  }
});

module.exports = router;

# routes/checkout.py
from flask import Blueprint, request, jsonify
import requests
import os

checkout = Blueprint('checkout', __name__)

@checkout.route('/create-checkout', methods=['POST'])
def create_checkout():
    data = request.get_json()

    response = requests.post(
        'https://api.recur.tw/v1/checkout/sessions',
        headers={
            'Authorization': f'Bearer {os.environ["RECUR_SECRET_KEY"]}',
            'Content-Type': 'application/json',
        },
        json={
            'productId': data['productId'],
            'mode': 'SUBSCRIPTION',
            'successUrl': f'{os.environ["APP_URL"]}/success?session_id={{CHECKOUT_SESSION_ID}}',
            'cancelUrl': f'{os.environ["APP_URL"]}/pricing',
        }
    )

    result = response.json()

    if not response.ok:
        return jsonify({'error': result.get('error')}), response.status_code

    return jsonify({'url': result['url']})

前端導向

在前端呼叫您的後端 API，然後導向返回的 URL：

// components/SubscribeButton.tsx
'use client';

export function SubscribeButton({ productId }: { productId: string }) {
  const [loading, setLoading] = useState(false);

  const handleClick = async () => {
    setLoading(true);

    try {
      const response = await fetch('/api/create-checkout', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ productId }),
      });

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

      if (error) {
        alert('發生錯誤：' + error.message);
        return;
      }

      // 導向 Recur 結帳頁面
      window.location.href = url;
    } finally {
      setLoading(false);
    }
  };

  return (
    <button onClick={handleClick} disabled={loading}>
      {loading ? '處理中...' : '立即訂閱'}
    </button>
  );
}

Success URL 處理

用戶完成付款後，會被導向您設定的 successUrl。URL 中會包含 {CHECKOUT_SESSION_ID} 佔位符的實際值：

https://your-site.com/success?session_id=cs_abc123xyz

您可以使用這個 Session ID 來：

驗證付款狀態 - 呼叫 GET /v1/checkout/sessions/{id}
取得訂閱資訊 - 從 Session 中取得 subscriptionId
更新使用者狀態 - 在您的資料庫中標記用戶已訂閱

// app/success/page.tsx
import { notFound } from 'next/navigation';

export default async function SuccessPage({
  searchParams,
}: {
  searchParams: { session_id?: string };
}) {
  const sessionId = searchParams.session_id;

  if (!sessionId) {
    notFound();
  }

  // 驗證 Session 狀態
  const response = await fetch(
    `https://api.recur.tw/v1/checkout/sessions/${sessionId}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.RECUR_SECRET_KEY}`,
      },
    }
  );

  const session = await response.json();

  if (session.status !== 'COMPLETE') {
    return <div>付款尚未完成</div>;
  }

  return (
    <div>
      <h1>感謝您的訂閱！</h1>
      <p>訂單編號：{session.orderId}</p>
      <p>訂閱編號：{session.subscriptionId}</p>
    </div>
  );
}

設定 Webhook

重要：不要只依賴 successUrl 來確認付款。用戶可能在付款完成前關閉瀏覽器。請務必設定 Webhook 來接收付款通知。

結帳模式

SUBSCRIPTION（訂閱）

{
  "productId": "prod_monthly",
  "mode": "SUBSCRIPTION",
  "successUrl": "https://example.com/welcome",
  "cancelUrl": "https://example.com/pricing"
}

建立週期性訂閱
自動綁定付款方式
後續會自動扣款

PAYMENT（一次性付款）

{
  "productId": "prod_ebook",
  "mode": "PAYMENT",
  "successUrl": "https://example.com/download",
  "cancelUrl": "https://example.com/shop"
}

單次付款
不建立訂閱關係
適合數位商品、實體商品

SETUP（僅儲存卡片）

{
  "productId": "prod_xxx",
  "mode": "SETUP",
  "successUrl": "https://example.com/card-saved",
  "cancelUrl": "https://example.com/settings"
}

不扣款，僅儲存付款方式
用於升級流程、試用結束後收費
返回 setupIntentId 而非 paymentIntentId

客製化選項

預填客戶資訊

{
  "customerEmail": "user@example.com"
}

使用 Metadata

{
  "metadata": {
    "userId": "user_123",
    "plan": "pro",
    "referrer": "homepage"
  }
}

metadata 僅在使用 Secret Key 時可用。Publishable Key 無法設定 metadata。

錯誤處理

常見錯誤和處理方式：

錯誤代碼	原因	解決方式
`resource_not_found`	商品不存在	確認 productId 正確
`invalid_request`	URL 格式錯誤	確認 successUrl/cancelUrl 為 HTTPS
`unauthorized`	API Key 無效	檢查 Secret Key

下一步

Webhook 整合 - 接收付款通知
Embedded Checkout - 嵌入式結帳
API Reference - 完整 API 文件

Hosted Checkout

Hosted Checkout 是最簡單的整合方式。您只需在後端建立 Checkout Session，然後將用戶導向 Recur 託管的結帳頁面。

適合場景：

快速上線，無需開發前端 UI
想使用 Recur 最佳化的結帳體驗
不需要完全客製化結帳頁面

運作流程

1. 用戶點擊「訂閱」按鈕
   ↓
2. 您的後端呼叫 POST /v1/checkout/sessions
   ↓
3. Recur 返回 Checkout Session URL
   ↓
4. 前端導向該 URL
   ↓
5. 用戶在 Recur 結帳頁面完成付款
   ↓
6. 重新導向回 successUrl 或 cancelUrl

建立 Checkout Session

API 端點

POST https://api.recur.tw/v1/checkout/sessions

請求參數

參數	必填	說明
`productId`	✅	商品 ID
`mode`	❌	`PAYMENT`（一次性）、`SUBSCRIPTION`（訂閱）、`SETUP`（僅儲存卡片）
`successUrl`	✅	成功後的重新導向 URL
`cancelUrl`	✅	取消時的重新導向 URL
`customerEmail`	❌	預填客戶 Email
`metadata`	❌	自訂 metadata（僅 Secret Key 可用）

程式碼範例

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

export async function POST(request: Request) {
  const body = await request.json();

  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: body.productId,
      mode: 'SUBSCRIPTION',
      successUrl: `${process.env.NEXT_PUBLIC_URL}/success?session_id={CHECKOUT_SESSION_ID}`,
      cancelUrl: `${process.env.NEXT_PUBLIC_URL}/pricing`,
      customerEmail: body.email,
      metadata: {
        userId: body.userId,
      },
    }),
  });

  const data = await response.json();

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

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

// routes/checkout.js
const express = require('express');
const router = express.Router();

router.post('/create-checkout', async (req, res) => {
  try {
    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: req.body.productId,
        mode: 'SUBSCRIPTION',
        successUrl: `${process.env.APP_URL}/success?session_id={CHECKOUT_SESSION_ID}`,
        cancelUrl: `${process.env.APP_URL}/pricing`,
      }),
    });

    const data = await response.json();

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

    res.json({ url: data.url });
  } catch (error) {
    res.status(500).json({ error: 'Internal server error' });
  }
});

module.exports = router;

# routes/checkout.py
from flask import Blueprint, request, jsonify
import requests
import os

checkout = Blueprint('checkout', __name__)

@checkout.route('/create-checkout', methods=['POST'])
def create_checkout():
    data = request.get_json()

    response = requests.post(
        'https://api.recur.tw/v1/checkout/sessions',
        headers={
            'Authorization': f'Bearer {os.environ["RECUR_SECRET_KEY"]}',
            'Content-Type': 'application/json',
        },
        json={
            'productId': data['productId'],
            'mode': 'SUBSCRIPTION',
            'successUrl': f'{os.environ["APP_URL"]}/success?session_id={{CHECKOUT_SESSION_ID}}',
            'cancelUrl': f'{os.environ["APP_URL"]}/pricing',
        }
    )

    result = response.json()

    if not response.ok:
        return jsonify({'error': result.get('error')}), response.status_code

    return jsonify({'url': result['url']})

前端導向

在前端呼叫您的後端 API，然後導向返回的 URL：

// components/SubscribeButton.tsx
'use client';

export function SubscribeButton({ productId }: { productId: string }) {
  const [loading, setLoading] = useState(false);

  const handleClick = async () => {
    setLoading(true);

    try {
      const response = await fetch('/api/create-checkout', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ productId }),
      });

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

      if (error) {
        alert('發生錯誤：' + error.message);
        return;
      }

      // 導向 Recur 結帳頁面
      window.location.href = url;
    } finally {
      setLoading(false);
    }
  };

  return (
    <button onClick={handleClick} disabled={loading}>
      {loading ? '處理中...' : '立即訂閱'}
    </button>
  );
}

Success URL 處理

用戶完成付款後，會被導向您設定的 successUrl。URL 中會包含 {CHECKOUT_SESSION_ID} 佔位符的實際值：

https://your-site.com/success?session_id=cs_abc123xyz

您可以使用這個 Session ID 來：

驗證付款狀態 - 呼叫 GET /v1/checkout/sessions/{id}
取得訂閱資訊 - 從 Session 中取得 subscriptionId
更新使用者狀態 - 在您的資料庫中標記用戶已訂閱

// app/success/page.tsx
import { notFound } from 'next/navigation';

export default async function SuccessPage({
  searchParams,
}: {
  searchParams: { session_id?: string };
}) {
  const sessionId = searchParams.session_id;

  if (!sessionId) {
    notFound();
  }

  // 驗證 Session 狀態
  const response = await fetch(
    `https://api.recur.tw/v1/checkout/sessions/${sessionId}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.RECUR_SECRET_KEY}`,
      },
    }
  );

  const session = await response.json();

  if (session.status !== 'COMPLETE') {
    return <div>付款尚未完成</div>;
  }

  return (
    <div>
      <h1>感謝您的訂閱！</h1>
      <p>訂單編號：{session.orderId}</p>
      <p>訂閱編號：{session.subscriptionId}</p>
    </div>
  );
}

設定 Webhook

重要：不要只依賴 successUrl 來確認付款。用戶可能在付款完成前關閉瀏覽器。請務必設定 Webhook 來接收付款通知。

結帳模式

SUBSCRIPTION（訂閱）

{
  "productId": "prod_monthly",
  "mode": "SUBSCRIPTION",
  "successUrl": "https://example.com/welcome",
  "cancelUrl": "https://example.com/pricing"
}

建立週期性訂閱
自動綁定付款方式
後續會自動扣款

PAYMENT（一次性付款）

{
  "productId": "prod_ebook",
  "mode": "PAYMENT",
  "successUrl": "https://example.com/download",
  "cancelUrl": "https://example.com/shop"
}

單次付款
不建立訂閱關係
適合數位商品、實體商品

SETUP（僅儲存卡片）

{
  "productId": "prod_xxx",
  "mode": "SETUP",
  "successUrl": "https://example.com/card-saved",
  "cancelUrl": "https://example.com/settings"
}

不扣款，僅儲存付款方式
用於升級流程、試用結束後收費
返回 setupIntentId 而非 paymentIntentId

客製化選項

預填客戶資訊

{
  "customerEmail": "user@example.com"
}

使用 Metadata

{
  "metadata": {
    "userId": "user_123",
    "plan": "pro",
    "referrer": "homepage"
  }
}

metadata 僅在使用 Secret Key 時可用。Publishable Key 無法設定 metadata。

錯誤處理

常見錯誤和處理方式：

錯誤代碼	原因	解決方式
`resource_not_found`	商品不存在	確認 productId 正確
`invalid_request`	URL 格式錯誤	確認 successUrl/cancelUrl 為 HTTPS
`unauthorized`	API Key 無效	檢查 Secret Key

下一步

Webhook 整合 - 接收付款通知
Embedded Checkout - 嵌入式結帳
API Reference - 完整 API 文件

Hosted Checkout

Hosted Checkout

運作流程

建立 Checkout Session

API 端點

請求參數

程式碼範例

前端導向

Success URL 處理

設定 Webhook

結帳模式

SUBSCRIPTION（訂閱）

PAYMENT（一次性付款）

SETUP（僅儲存卡片）

客製化選項

預填客戶資訊

使用 Metadata

錯誤處理

下一步

On this page

Hosted Checkout

Hosted Checkout

運作流程

建立 Checkout Session

API 端點

請求參數

程式碼範例

前端導向

Success URL 處理

設定 Webhook

結帳模式

SUBSCRIPTION（訂閱）

PAYMENT（一次性付款）

SETUP（僅儲存卡片）

客製化選項

預填客戶資訊

使用 Metadata

錯誤處理

下一步

On this page