Webhooks
Webhooks 為關鍵的支付生命週期更新提供實時、事件驅動的通知。 Cardflo 的 webhooks 使您的系統能夠即時回應支付狀態、爭議及其他關鍵事件。
自動化工作流程並保持您的平台與 Cardflo 之間的同步，而無需持續輪詢。
- 類別
- 開發者
- 功能數
- 10
- 適用於
- 所有方案
概覽
Webhooks 作為非同步 HTTP 回調，促進支付網關與商戶伺服器之間的實時通信。 與傳統的輪詢方法（伺服器重複發出請求以檢查狀態更新）不同，webhooks 在支付生命週期中發生特定事件時，立即將數據推送到預定義的 URL。
這種機制對於管理非同步事件至關重要，例如 3-D Secure 身份驗證結果、非同步替代支付方式 (APM) 完成，或收到退單。 在支付堆棧中，webhooks 充當收單機構或 PSP 與商戶內部訂單管理系統 (OMS) 或收入管理平台之間的連接紐帶。
它們確保後續邏輯（例如庫存鎖定或數字權利）保持準確，而不會引入延遲或不必要的 API 開銷。
正確實施需要穩健處理 HTTP 狀態碼和冪等性，以管理來自發送伺服器的潛在重試，確保每個事件只處理一次。
運作方式
定義端點和事件
商戶在其環境中指定一個目標 URL 以接收 POST 請求。 他們從支付生命週期中選擇特定的事件觸發器，例如授權成功、退款發起或爭議創建。
這確保他們的系統只處理相關數據包，減少不必要的伺服器負載，並使集成點保持專注和易於管理。
事件觸發和負載
當狀態發生變化時，例如客戶完成 SCA 挑戰，系統會生成一個 JSON 負載。 此負載包含結構化數據，包括交易 ID、商戶 ID (MID)、金額和特定事件類型。
然後，網關嘗試將此數據交付到註冊的端點。
安全和簽名驗證
為防止未經授權的數據注入，負載通常使用密鑰簽名。 商戶伺服器使用原始請求主體重建簽名，並將其與標頭進行比較。
此驗證確保數據源自受信任的來源，並且在傳輸過程中未被篡改。
確認和處理
商戶伺服器必須及時返回 200 OK 狀態碼以確認收到。 然後執行內部邏輯，例如更新數據庫記錄或觸發自動電子郵件。
如果伺服器離線或返回錯誤，交付系統會遵循預設的重試排程以確保數據一致性。
為何重要
營運效率和自動化
依賴手動狀態檢查或定期 API 輪詢會引入延遲，從而降低用戶體驗並延遲履行。 Webhooks 自動化支付授權和服務交付之間的轉換。
通過接收成功請款或結算的即時通知，企業可以自動化運輸工作流程、許可證生成或帳戶配置，減少手動干預的需求，並最大程度地降低交易管理中人為錯誤的風險。
風險和爭議緩解
檢索請求或退單的通知允許商戶在方案規定的時間範圍內回應。 關於軟拒絕或 SCA 失敗的即時警報可以實現主動的客戶參與。
通過對這些事件的即時反應，商戶可以提高其申訴成功率，並降低與未解決的支付失敗或爭議相關的營運成本，否則這些失敗或爭議可能在定期手動審核之前未被發現。
應用案例
訂閱和 SaaS 生命週期
當定期付款失敗或卡片過期時，webhook 會觸發自動催收序列或暫停用戶訪問，在沒有手動監督的情況下保持準確的計費週期。
電子商務訂單履行
在收到「capture. succeeded」事件後，在線零售商使用 webhooks 才會發貨，防止發送尚未完全授權付款的商品。
市場支付協調
接收資金的平台只有在初始客戶交易達到結算狀態後才能觸發向子商戶的支付，從而確保流動性並降低支付逆轉的風險。
替代支付方式最終確定
對於銀行轉帳或本地方案等不提供即時確認的方法，webhooks 會在資金確認後數小時或數天通知系統。
數據概覽
事件在收單平台中記錄與 webhook 派發到商戶端點之間的典型行業延遲。
包含自動重試邏輯和冗餘交付基礎設施時，webhook 服務的標準可靠性基準。
從定期批處理過渡到事件驅動的 webhook 架構時，履行速度的行業觀察改進。
Talk to our team about a live rollout on your acquiring stack.
為您帶來 Webhooks
- 交易狀態變更的非同步交付，以提高系統效能。
- 支援多種事件類型，包括授權、請款、退款和爭議。
- HMAC-SHA256 簽名標頭，用於穩健驗證傳入數據的完整性。
- 在交付失敗後，按照指數退避排程自動重試。
- 負載版本控制，以確保數據結構隨時間演變時的兼容性。
- IP 白名單功能，以限制傳入流量僅來自已知的網關來源。
- 包含冪等性密鑰，以防止重複處理相同的支付事件。
- 詳細的事件日誌，用於在儀表板中調試和審核 webhook 交付效能。
- 精細的事件選擇，以最大程度地減少帶寬使用和伺服器端處理要求。
- 測試模式功能，用於通過模擬支付場景驗證端點行為。
A short scoping call, then a written plan for your MIDs.
關於 Webhooks
我們的伺服器應如何處理重複的 webhook 通知？
支付網關採用重試機制是標準做法，如果端點在特定時間範圍內未返回 200 OK 回應。 因此，您的伺服器可能會多次收到相同的事件。
為保持數據完整性，您應實施冪等性邏輯。 這通常涉及追蹤負載中提供的唯一事件 ID，並在執行任何業務邏輯之前檢查其是否已處理。
如果 ID 存在於您的數據庫中，您的伺服器應忽略該事件，但仍返回 200 OK 以停止進一步的重試。
輪詢 API 與使用 webhooks 有何區別？
輪詢要求您的伺服器頻繁向網關發出請求以檢查狀態更新，這效率低下，並可能導致速率限制問題或信息延遲。 Webhooks 則反轉了這種流程，網關僅在事件發生時才向您的伺服器發出請求。
這種「推送」模型效率更高，減少了伺服器負載，並確保狀態在您的基礎設施中近乎實時地更新，這對於數字內容交付或欺詐預防等時間敏感的操作尤為重要。
為什麼每個 webhook 請求都需要簽名驗證？
由於 webhook 端點是公共 URL，理論上任何互聯網上的實體都可以訪問它們。 如果沒有驗證，攻擊者可能會向您的伺服器發送偽造的 JSON 負載，錯誤地指示高價值支付成功。
通過使用共享密鑰驗證請求標頭中提供的 HMAC 簽名，您的系統可以數學證明消息是由您的 PSP 發送的，並且內容未被篡改，從而確保您的訂單履行過程的安全性。
webhooks 如何處理 3-D Secure 和 SCA 要求？
在 3-DS 流程中，交易通常會進入待處理狀態，同時用戶被重定向到其發卡機構進行身份驗證。 此身份驗證的最終結果可能無法立即得知。
Webhooks 用於在 3-DS 挑戰完成且交易隨後被授權或拒絕時通知您的系統。 這可以防止您的結帳掛起，並允許您的後端在客戶從銀行重定向頁面返回後對最終授權狀態做出反應。
webhooks 可以用於管理退單和爭議時間表嗎？
是的，webhooks 是管理爭議生命週期的主要工具。 當持卡人向其發卡機構發起檢索請求或正式退單時，網關會通過卡組織收到此通知。
然後，webhook 會發送到您的系統，指定原因代碼、金額和回應截止日期。 利用這些實時數據，您可以自動暫停相關帳戶並通知您的風險團隊立即啟動申訴流程，從而增加成功撤銷爭議的可能性。
如果我們的伺服器在關鍵 webhook 事件期間停機，會發生什麼？
可靠的 webhook 系統採用重試策略。 如果您的端點返回 4xx 或 5xx 錯誤，或未能在幾秒鐘內回應，網關將將消息排隊以重新交付。
這些重試通常遵循指數退避模式，在幾分鐘或幾小時內嘗試交付多次。
為確保長期一致性，您還應具備備用機制，例如每日對帳腳本，該腳本調用 API 以查找任何錯過的狀態更改，為長時間停機提供安全網。