信用卡在 Pagou API 中
請先套用技能 pagou 的規則（環境、後端驗證、安全性與不確定結果）。此技能僅提供信用卡的決策。欄位與 payload 位於下列頁面：請在實作前閱讀它們。
實作前請先閱讀
- 付款方式：信用卡
- 令牌化一張卡片
- 建立一筆收款
- 查詢與列出收款
- 冪等性與重複
- 參考流程：建立客戶（付款人）、建立一張卡片、管理付款人 與 管理卡片
- 當流程要求時：擷取一筆已授權的收款、取消一筆收款、退款一筆收款、執行一次重試、更新一筆收款 與 Chargebacks
- 啟用帳戶：申請註冊
先決條件
帳號啟用中、信用卡註冊已核准、已設定信用卡費率的方案以及有效的金鑰。註冊需透過控制面板申請，非經由 API。如果帳號尚未註冊，請在實作前告知使用者。
強制架構
- 瀏覽器： 自訂結帳頁面收集卡片資料，並使用 Pagou 的令牌化函式庫生成 token，該函式庫必須與收款所使用的 API 環境相同。此函式庫使用的公鑰不是
X-API-KEY。 - 瀏覽器到後端： 僅將 token 化的
card物件與購買資料傳送至商店伺服器。令牌化完成後，請清除表單狀態中的卡號與 CVV。 - 商家後端： 使用
X-API-KEY在 API 中建立收款，此金鑰絕不應存在於瀏覽器中。
完整卡號與 CVV 不屬於 API 合約的一部分。請勿在日誌、分析工具或瀏覽器儲存中記錄卡號、CVV 或 token。Pagou 結帳頁面已處理令牌化：此架構適用於自訂結帳頁面。
決策規則
-
金額以整數分為單位：
value: 5000代表 R$ 50.00。請勿沿用 Pix 或銀行條碼的單位。 -
確切選擇一種流程：
- 完整資料：
customer與card物件（含 token）。 - 參考：同一付款人的
customer_id與card_id，均需屬於已驗證的帳號。此流程中不需生成新的 token。
請勿混合兩種流程，也不要只發送配對中的一個元素。在完整流程中，請儲存回傳的 ID 以供後續重複使用。
- 完整資料：
-
防詐欺： 遵循文件要求，包括購買者的真實 IP。切勿使用範例中的示意 IP。
-
分期付款： 遵守發卡組織的限制，且卡片不能已過期。
-
根據
status判斷財務結果：201不保證核准。區分authorized（授權）、captured（擷取）與settled（已結算）。收款的unknown狀態與溝通錯誤導致的不確定結果不同。 -
擷取不是固定步驟： 建立收款時可能已回傳
captured。僅對持續處於authorized狀態且商業意圖需要時，才呼叫明確的擷取。切勿使用擷取來解決逾時問題。 -
取消或退款： 取消適用於待處理的收款；已授權、已擷取或已結算的收款則遵循退款規則，目前在合約中為全額退款。請先確認狀態再選擇。
-
重試 (
/retry)： 這是另一項財務操作，僅在確認失敗後（failed），使用專屬金鑰且在文件限制內執行。切勿使用/retry來解決逾時或不確定結果。 -
Chargebacks： 在爭議操作中使用 chargeback 的
id；爭議狀態與收款的charged_back狀態不同。辯護與接受是商家決策：僅在要求時實作。 -
分帳： 請遵循技能
pagou-split；信用卡收款使用分為單位，但分帳的固定金額使用實際貨幣單位。
冪等性
- 每筆商業操作（註冊付款人、註冊卡片、建立收款、擷取、退款、重試）生成一個唯一的
Idempotency-Key，並在首次發送前將其與請求一同儲存。 - 要重複相同操作，請保持相同的金鑰、方法、路徑以及請求主體的位元組，包括
card_token與分帳陣列。請勿重新組裝 JSON。 - 新購買需要新金鑰；可以重複使用
customer_id與card_id。 - 請勿在迴圈內生成新金鑰，也不要為了繞過逾時而這麼做。
- 代碼
idempotency_key_conflict、idempotency_in_progress與idempotency_outcome_unknown有各自不同的處理方式：請閱讀冪等性頁面。不確定結果需要透過查詢來調查，而非發起新收款。
MCP 工具
Pagou 的 MCP 僅能讀取 信用卡收款：
| 工具 | 用途 |
|---|---|
get_card_charge | 根據 ID 查詢一筆收款 |
list_card_charges | 根據狀態與時間區間列出與核對收款 |
MCP 不會建立、擷取、取消、退款或重試信用卡收款，不會管理付款人或卡片，也不會處理 chargebacks。建立動作發生在商家後端，在瀏覽器令牌化之後。請勿嘗試從代理工具經由其他途徑建立信用卡收款。
Sandbox 測試
- 確認 Sandbox 帳號符合信用卡的先決條件。
- 在 Sandbox 環境中對測試卡號
4111 1111 1111 1111進行令牌化，請依照令牌化頁面操作。 - 從應用程式的後端，針對
https://api.pagou.cloud使用 Sandbox 金鑰與專屬的Idempotency-Key建立收款。Pix 的模擬路由不適用於信用卡。 - 檢查回傳的
status並查詢同一筆收款（也可使用get_card_charge）。 - 使用相同金鑰重複發送相同請求，並確認不會產生重複的收款。