PayPal

後台位置： Finance › Payment channels › PayPal (/payments/paypal)。開關與手續費位於 Finance › Payment channels › Fees & limits (/payments/fees)。

功能

讓客戶能夠使用其 PayPal 餘額、銀行帳戶或保存在 PayPal 的卡片來加值 USD 錢包。客戶也可以讓 NexCMP 記住其 PayPal 帳戶以便進行 自動加值。對於偏好 PayPal 的客戶，可與 Stripe 搭配使用。

需求

項目	需求
PayPal 帳戶	可接收 USD 的 PayPal 商務帳戶。
REST 應用程式	PayPal 開發人員儀表板（Apps & Credentials）中的一個 REST 應用程式，可提供 Client ID 與 Client secret。請使用 Sandbox 標籤頁進行測試，Live 用於正式環境。
網路	必須能從網際網路透過 HTTPS 連線（PayPal 會呼叫 Webhook），且對外能連線至 api-m.paypal.com（正式）或 api-m.sandbox.paypal.com（沙箱），連接埠 443。
權限	REST 應用程式需要退款和 Webhook 功能。Check 對話框會顯示這兩個範圍是否存在。
相依項目	無。

準備基礎設施

1. 使用您的商務帳戶登入 developer.paypal.com 並開啟 Apps & Credentials。
2. 選擇 Sandbox（測試）或 Live，然後點擊 Create App。為其命名，例如「NexCMP」。
3. 複製應用程式的 Client ID 與 Secret。
4. 若要進行測試，請使用 Testing Tools › Sandbox Accounts 來尋找或建立個人（買家）沙箱帳戶。
5. 您不需要自行建立 webhook；NexCMP 會透過 Create webhook 按鈕建立它。

在 NexCMP 中連線

1. 開啟 Finance › Payment channels › PayPal (/payments/paypal)。
2. 在 API keys 中，選擇 Mode：live（真實金錢，api-m.paypal.com）或 sandbox（api-m.sandbox.paypal.com）。
3. 貼上 Client ID（至少 20 個字元）與 Client secret。
4. 點擊 Check。它會測試您輸入的憑證（不需要儲存），並回報連線狀況、App ID、模式、是否具備退款與 webhooks 權限範圍，以及權杖的有效期限。
5. 點擊 Save。
6. 在 Webhook 卡片中確認 URL 為 https://<your-domain>/v1/billing/paypal/webhook（必須是 https），然後點擊 Create webhook 並確認。NexCMP 會要求 PayPal 建立或更新包含 11 個事件的 webhook，並儲存傳回的 Webhook ID。此按鈕會使用已儲存的金鑰——如果您剛剛編輯過，請先儲存。
7. 再次點擊 Check：Webhook 列應顯示「exists, 11 events」。
8. 開啟 Fees & limits，將 PayPal 開啟，將 PayPal fee %（預設為 4.4）與 PayPal fixed fee (cents)（預設為 30）設定為您的費率，然後點擊 Save channels & fees。

Webhook events

NexCMP 會註冊這 11 個事件：CHECKOUT.ORDER.APPROVED、PAYMENT.CAPTURE.COMPLETED、PAYMENT.CAPTURE.PENDING、PAYMENT.CAPTURE.DECLINED、PAYMENT.CAPTURE.REFUNDED、PAYMENT.CAPTURE.REVERSED、CUSTOMER.DISPUTE.CREATED、CUSTOMER.DISPUTE.UPDATED、CUSTOMER.DISPUTE.RESOLVED、RISK.DISPUTE.CREATED、CHECKOUT.PAYMENT-APPROVAL.REVERSED。

每個 webhook 都會透過呼叫 PayPal 的簽章驗證 API 進行驗證，儲存一次並以冪等方式處理。NexCMP 絕不信任 webhook 內文中的金額：在將金額存入款項之前，它會從 PayPal 取得該筆請款資料。

驗證

1. 將Mode保持在sandbox。在入口網站中，前往Billing › Deposit，選擇PayPal，點擊Continue on PayPal（或 PayPal 按鈕），並使用 sandbox 買家帳號登入。
2. 核准付款。您將返回入口網站，餘額會增加，且該筆付款會顯示在 Finance › Billing › Top-ups 下方，狀態為 Completed。
3. 開啟 Payment channels › Gateway events › PayPal & USDT：將會列出 PAYMENT.CAPTURE.COMPLETED 事件。
4. 當一切運作正常時，將 Mode 切換為 live，輸入正式憑證，點擊 Save，然後再次點擊 Create webhook（沙盒與正式的 webhook 是分開的）。

限制與注意事項

• 付款如何完成。 訂單以 USD 建立；在客戶核准後，伺服器會進行請款（具備冪等請求 ID）並精確將錢包加值一次。如果客戶關閉瀏覽器，webhook 與每 10 分鐘執行一次的對帳作業將作為安全網。
• 待處理與放棄的訂單。 訂單最多可保持開啟 12 小時。客戶最多可擁有 5 筆待處理訂單（伺服器會回應 too_many_pending，HTTP 429）。超過 24 小時仍未請款的訂單將被標記為失敗。
• 未設定 webhook。 在儲存 Webhook ID 之前，面板會對每個 PayPal webhook 回應 HTTP 503。透過入口網站與 10 分鐘對帳所進行的請款仍會存入錢包，但 PayPal 透過 webhook 回報的任何事件（爭議、退款、延遲請款）都不會被套用——請點擊 Create webhook。
• 已儲存的 PayPal 帳戶。 當客戶選擇儲存 PayPal（或完成首次儲存，這會啟用 automatic top-up）時，PayPal 會將付款權杖儲存在其保險庫中。NexCMP 僅保留識別碼與 PayPal 電子郵件。請參閱 Saved payment methods。
• 退款與爭議的處理方式與 Stripe 類似：退款請求會在 Finance › Payouts › Card refunds 下方獲得核准；爭議會凍結客戶的帳戶並暫停其預付服務，直到您解決為止。
• 手續費。 PayPal 的手續費不會被讀回；您設定的百分比與固定手續費決定了客戶看到的金額以及存入的金額。實際費率取決於您的國家（表單提示越南為 4.4%、美國為 3.49%）。

故障排除

症狀	原因	修正方式
「Client ID太短」	貼上的字元少於 20 個	複製完整的 Client ID。
「Webhook URL 必須使用 https」	輸入的 URL 包含 http://	請使用您的公開 https:// 網域。
檢查回報連線錯誤	模式錯誤（沙盒環境使用正式密鑰或反之）、密鑰錯誤、無對外連線能力	將 Mode 與密鑰類型相符；從伺服器測試 curl -I https://api-m.paypal.com。
範圍退款 / webhooks 顯示「no」	REST 應用程式缺少功能	在 PayPal Developer Dashboard 的應用程式中啟用功能。
橫幅「PayPal key set, NO webhook」	缺少 Webhook ID	點擊 Create webhook。
檢查中出現 "Webhook not found"	Webhook 已在 PayPal 刪除或屬於其他應用程式	再次點擊 Create webhook。
客戶收到 PayPal 拒絕付款的訊息	PayPal 拒絕該資金來源	請客戶選擇其他付款來源。
客戶看到 "Too many pending requests"	5 個未結訂單	等待它們過期或完成它們。
缺少 PayPal 按鈕	PayPal 在 Fees & limits 中關閉或未設定	將其開啟並儲存憑證。