快速開始
API 認證
了解如何使用 API Key 認證 Recur API
API 認證
Recur API 使用 API Key 進行認證。本文件說明不同類型的 API Key 及其使用方式。
API Key 類型
Recur 提供兩種類型的 API Key：
| 類型 | 前綴 | 用途 | 權限 |
|---|---|---|---|
| Secret Key | sk_xxx | 後端使用 | 完整權限 |
| Publishable Key | pk_xxx | 前端使用 | 限制權限 |
Secret Key
Secret Key 擁有完整的 API 權限，包括：
- 建立和管理 Checkout Sessions
- 讀取訂單和訂閱資料
- 設定 metadata
- 取消訂閱
安全警告：Secret Key 必須保密，只能在後端伺服器使用。切勿：
- 在前端代碼中使用
- 提交到版本控制系統
- 在公開場合分享
Publishable Key
Publishable Key 用於前端整合，權限受限：
- 載入結帳表單
- 取得商品/方案資訊
- 初始化 SDK
Publishable Key 可以安全地在前端代碼中使用，但仍建議限制使用網域。
環境
Recur 提供兩個環境：
| 環境 | Key 前綴 | 用途 | 金流 |
|---|---|---|---|
| Sandbox | sk_test_ / pk_test_ | 測試環境 | 模擬付款 |
| Production | sk_live_ / pk_live_ | 正式環境 | 真實付款 |
Sandbox 環境
使用 Sandbox 環境進行開發和測試：
- 使用測試 API Key（
sk_test_xxx） - 使用 PAYUNi 測試卡號
- 不會產生真實交易
測試卡號：
卡號：4147-6310-0000-0001
有效期：任意未過期日期
CVV：任意 3 位數Production 環境
上線前，請確保：
- 將所有 API Key 替換為正式環境的 Key
- 完成 升級正式環境 流程
- 設定正確的 Webhook URL
認證方式
Authorization Header（推薦）
curl https://api.recur.tw/v1/checkout/sessions \
-H "Authorization: Bearer sk_test_xxx"專用 Header
# Secret Key
curl https://api.recur.tw/v1/checkout/sessions \
-H "X-Recur-Secret-Key: sk_test_xxx"
# Publishable Key
curl https://api.recur.tw/v1/products \
-H "X-Recur-Publishable-Key: pk_test_xxx"在程式碼中使用
Node.js / TypeScript
// 使用環境變數儲存 API Key
const RECUR_SECRET_KEY = process.env.RECUR_SECRET_KEY;
const response = await fetch('https://api.recur.tw/v1/checkout/sessions', {
method: 'POST',
headers: {
'Authorization': `Bearer ${RECUR_SECRET_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
productId: 'prod_xxx',
mode: 'SUBSCRIPTION',
successUrl: 'https://example.com/success',
cancelUrl: 'https://example.com/cancel',
}),
});前端 SDK
import { RecurProvider } from 'recur-tw';
function App() {
return (
<RecurProvider publishableKey="pk_test_xxx">
{/* 您的應用程式 */}
</RecurProvider>
);
}取得 API Key
- 登入 Recur 後台
- 前往 設定 → 開發者 → API 金鑰
- 點擊「顯示」查看完整 Key
- 使用「重新產生」來輪換 Key
安全最佳實踐
- 使用環境變數 - 不要硬編碼 API Key
- 最小權限原則 - 前端只用 Publishable Key
- 定期輪換 - 定期重新產生 API Key
- 監控使用量 - 在後台查看 API 呼叫記錄
- 限制網域 - 設定允許使用 Publishable Key 的網域
# .env.local
RECUR_SECRET_KEY=sk_test_xxx
NEXT_PUBLIC_RECUR_PUBLISHABLE_KEY=pk_test_xxx錯誤處理
認證相關的常見錯誤：
| HTTP 狀態 | 錯誤代碼 | 說明 |
|---|---|---|
| 401 | unauthorized | API Key 無效或缺失 |
| 403 | forbidden | API Key 無權限執行此操作 |
{
"error": {
"code": "unauthorized",
"message": "Invalid API key provided"
}
}下一步
- 5 分鐘快速開始 - 實作第一個結帳流程
- API Reference - 完整 API 文件