# PayPal 付款與各國費率

## 各國費率(config/pricing.php)
- 課程定價一律以**新台幣(TWD)基準價**存放;學員在右上角選的國家/地區決定**顯示與收款的幣別與金額**(例如 NT$ 1,490 → 美國 US$ 50、日本 ¥7,100)。
- 匯率與取整單位(step)都在 `config/pricing.php`,是**預設參考值,不是即時匯率**。上線前請確認;也可在 `.env` 以 `PRICING_RATES=USD=31.5,JPY=0.21` 覆寫(1 單位該幣別 = 多少新台幣)。
- PayPal 不支援的國家(例如韓國、越南、印尼、印度、澳門、阿聯)一律以美元收款。
- 管理後台的訂單與銷售額仍以新台幣基準價統計;訂單另存實際收款的幣別與金額(`charge_currency` / `charge_amount`)。

## 付款方式(App\Services\Payments)
- 台灣:綠界(新台幣)與 PayPal 並列;其他國家:只有 PayPal。
- 都沒設定:正式環境禁止購買付費課程(`local` / `testing` 維持測試模式)。

## PayPal 流程(Orders v2,伺服器端)
1. 學員按「用 PayPal 付款」→ 系統建立 `pending` 訂單(金額由伺服器依當下價格與國家費率計算,瀏覽器傳來的金額一律忽略)→ 呼叫 PayPal 建立訂單 → 導向 PayPal 核准頁。
2. 學員核准後回到 `/payments/paypal/return/{order_no}?token=…`:伺服器 **capture**,並驗證:狀態 COMPLETED、`custom_id` = 訂單編號、**幣別與金額與訂單完全相符**。全部相符才標記已付款並開通課程;不符則標記失敗,不開通。
3. 背景通知(選用,備援):在 PayPal 開發者後台建立 Webhook,事件選 `PAYMENT.CAPTURE.COMPLETED`,網址 `https://你的網域/payments/paypal/webhook`,把 Webhook ID 填入 `PAYPAL_WEBHOOK_ID`。通知簽章驗證通過、且向 PayPal 查證後才開通。

## 設定
1. 到 https://developer.paypal.com 建立 App,取得 Client ID 與 Secret(先用 Sandbox 測試帳號)。
2. 在伺服器 `.env` 設定 `PAYPAL_ENV`(`sandbox` / `live`)、`PAYPAL_CLIENT_ID`、`PAYPAL_SECRET`,執行 `php artisan config:clear`。**金鑰不要提交到版本庫,也不要貼在對話或文件裡。**
3. 台灣學員若你的 PayPal 帳號不能收新台幣(TWD),設定 `PAYPAL_TWD_AS=USD`,台灣學員用 PayPal 時改收美元。
4. 先在 Sandbox 用測試買家帳號完整走一次(購買 → 核准 → 回站開通),再切 `PAYPAL_ENV=live`。

## 注意
- 退款、爭議、發票與對帳請到 PayPal 後台處理;系統不會自動退款或取消已開通的課程。
- 本系統的測試以假的 PayPal 回應驗證流程(tests/Feature/PayPalTest.php),**沒有**連到真的 PayPal;上線前請務必用 Sandbox 實測。
