支付網關怎麼接入網站?從零代碼到完整 API 的 4 種方式
支付網關接入方式對比:插件、易支付兼容接口、收款鏈接和 API 直連,各需要什麼、能做什麼,以及如何選擇最適合你的那一種。
支付網關接入,就是你的網站把買家交給支付服務商、並得知買家已付款的那套機制。它不一定意味着幾周的開發:根據你使用的系統,它可以是幾分鐘就能配置好的插件、一個貼到頁面上的鏈接,也可以是從服務端調用的 API。它們最終都可以通向同一個收銀台。
這篇文章對比在 KukoPay 上接入支付網關的四種方式:現成插件、易支付兼容接口、收款鏈接和 API 直連,説明每種方式需要你做什麼、能做什麼,以及無論選哪種都要遵守的規則。
四種接入方式對比
| 方式 | 適合 | 開發量 | 能做的事 |
|---|---|---|---|
| 現成插件 | 有官方插件的系統,比如 Xboard | 不寫代碼,填幾個配置 | 下單、收銀台、支付結果通知 |
| 易支付兼容接口 | 已經支持易支付協議的系統:V2Board、SSPanel、獨角數卡 | 不寫代碼,填網關地址、商戶 ID 和密鑰 | 下單、收銀台、支付成功通知、訂單查詢 |
| 收款鏈接 | 固定價格的商品或服務、賬單、捐助,沒有自己的訂單系統 | 不寫代碼,在控制台創建鏈接 | 收銀台、通知、收款筆數上限 |
| API 直連 | 自研系統,或需要在代碼裏處理退款、對賬和拒付 | 需要服務端開發 | 全部接口 |
在底層,所有方式用的都是同一套服務端 API、同一個託管收銀台和同一套簽名通知。區別只在於代碼由誰來寫。
方式一:現成插件
如果你的平台有官方插件,這是最短的路徑:在平台後台上傳插件,填入 API 密鑰和 Webhook 簽名密鑰,插件就會處理主流程:創建訂單、把買家帶到收銀台、收到通知後履約。
KukoPay 的插件從與文檔一起發佈的源碼構建,從 kukopay.com/downloads 下載,每個版本都附 SHA-256 校驗值,你可以核對安裝的是什麼。退款、拒付舉證和提現在商戶控制台操作,插件不需要支持這些功能。
方式二:易支付兼容接口
很多自建網店和面板已經支持易支付協議。如果你的系統支持,就完全不需要插件:填入 KukoPay 的網關地址(https://api.kukopay.com/epay)、商戶 ID(pid)和密鑰,就能收款。每筆易支付訂單都自帶通知地址。簽名規則、通知行為以及訂單有效期的坑,見 易支付接入指南。
方式三:收款鏈接
沒有平台,也不寫代碼?在控制台創建一個 收款鏈接,也就是一個打開即是收銀台的固定價格網址,放在「購買」按鈕後面、郵件裏或聊天裏。每次訪問都會生成一筆獨立訂單,通知和其他訂單一樣。這是最快的起步方式,很多商戶在接入 API 之後,仍然繼續用收款鏈接處理賬單和一次性銷售。
方式四:API 直連
對自研系統來説,API 給你全部能力:創建訂單、查詢訂單、退款、讀取資金流水、處理拒付。一個基礎的接入只需要兩步:
- 創建訂單,並把買家重定向到它的
checkout_url:
curl -X POST "https://api.kukopay.com/v1/orders" \
-H "Content-Type: application/json" \
-H "X-Api-Key: $KUKOPAY_API_KEY" \
-d '{
"out_trade_no": "ORD_20261108_0001",
"amount": 2990,
"currency": "USD",
"notify_url": "https://shop.example.com/webhooks/kukopay",
"return_url": "https://shop.example.com/orders/{OUT_TRADE_NO}/complete"
}'- 驗證 Webhook,收到
payment.succeeded時履約。
收銀台本身是託管的,所以卡號信息永遠不會到達你的服務器,見 託管收銀台是什麼。快速接入 完整演示了這個過程;在此基礎上,再加上用冪等鍵安全重試(見 冪等鍵是什麼)和錯誤處理(見 支付接口錯誤處理)。
如何選擇
- 你的平台有插件 → 用插件。
- 你的平台支持易支付 → 用易支付兼容接口。
- 你只賣幾樣固定價格的東西,或者想今天就開始 → 用收款鏈接。
- 你有自研系統,或者需要自動化處理退款和對賬 → 用 API。
這些方式可以混用:一個賬戶可以在一個網站上用插件、在另一個網站上用 API、再用收款鏈接處理賬單,每一套接入作為一個獨立的應用,有自己的密鑰,見 多個網站如何用一個商戶賬戶收款。
無論哪種方式都要遵守的規則
- 以通知或訂單查詢為準履約,永遠不要以買家回到你的網站為準,見 return_url 和 notify_url 的區別。
- 正式收款必須有地方接收通知。 要麼每筆訂單帶上公網 HTTPS 的
notify_url,要麼該應用有一個訂閲了payment.succeeded的 Webhook 端點,否則正式訂單會被拒絕。易支付訂單自帶通知地址,不受這條限制。 - 一套系統一個應用。 每套系統有自己的密鑰、訂單號和通知,資金仍在同一個賬戶裏。
- 測試憑證和正式憑證分開。 API 密鑰前綴(
kuko_test_/kuko_live_),或者易支付的pid,決定了環境,兩個環境的簽名密鑰也不同,見 沙箱環境和正式環境有什麼區別。
先試再選
每種方式都可以在沙箱裏跑通,不需要等待資質審核。先完成接入,測試成功、被拒和 Webhook,再切換到正式密鑰,測試場景見 支付測試卡號大全。
總結
- 支付網關接入可以是插件、易支付兼容接口、收款鏈接或 API 直連,最終都通向同一個託管收銀台;
- 插件和易支付不需要寫代碼,收款鏈接不需要訂單系統,API 提供完整的控制;
- 根據你的平台以及需要自動化的程度來選擇,也可以按應用混用多種方式;
- 無論選哪種,都要以通知履約、給正式訂單配置接收通知的地方,並把測試和正式憑證分開。
在沙箱裏把它跑通
註冊商戶後即可申請測試密鑰,不需要等待資質審核。