---
title: Customer Portal
description: 讓客戶自助管理訂閱的 Customer Portal 整合指南
---

# Customer Portal

Customer Portal 是一個託管的自助服務頁面，讓您的客戶可以管理他們的訂閱，而無需您開發額外的 UI。

## 功能概覽

Customer Portal 提供以下功能：

- **查看訂閱** - 顯示當前訂閱方案、價格、下次扣款日期
- **更新付款方式** - 安全地更新或新增信用卡
- **取消訂閱** - 客戶可自行取消訂閱
- **查看帳單歷史** - 瀏覽過去的付款記錄

  Portal 的外觀會自動套用您在後台設定的品牌樣式，包括 Logo 和主題顏色。

## 運作流程

```
1. 客戶在您的網站點擊「管理訂閱」
   ↓
2. 您的後端呼叫 POST /portal/sessions
   ↓
3. Recur 返回 Portal Session URL
   ↓
4. 前端導向該 URL
   ↓
5. 客戶在 Portal 管理訂閱
   ↓
6. 完成後重新導向回 returnUrl
```

## 整合方式

  
   按鈕快速整合"
    href="/guides/portal/client-integration"
  />

## 快速開始

### 1. 安裝 SDK

```bash
npm install recur-tw
```

### 2. 後端建立 Portal Session

```typescript
// app/api/portal/create/route.ts
import { Recur } from 'recur-tw/server';
import { NextRequest, NextResponse } from 'next/server';
import { getSession } from '@/lib/auth'; // 您的認證函數

const recur = new Recur(process.env.RECUR_SECRET_KEY!);

export async function POST(request: NextRequest) {
  // 驗證用戶身份
  const session = await getSession();
  if (!session) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  // 取得用戶對應的 Recur Customer ID
  const customerId = session.user.recurCustomerId;

  // 建立 Portal Session
  const portalSession = await recur.portal.sessions.create({
    customer: customerId,
    returnUrl: `${process.env.NEXT_PUBLIC_URL}/account`,
  });

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

### 3. 前端按鈕

```tsx
// components/ManageSubscriptionButton.tsx
'use client';

export function ManageSubscriptionButton() {
  const handleClick = async () => {
    const response = await fetch('/api/portal/create', {
      method: 'POST',
    });

    const { url } = await response.json();
    window.location.href = url;
  };

  return (
    <button onClick={handleClick}>
      管理訂閱
    </button>
  );
}
```

或使用 Web Component：

```html
<recur-portal api-endpoint="/api/portal/create">
  管理訂閱
</recur-portal>
```

## 安全性

  **重要**：Portal Session 必須在後端建立。

  - Portal API 需要 Secret Key 認證
  - 建立 Session 前務必驗證用戶身份
  - 確保用戶只能存取自己的 Customer Portal

## 下一步