跳轉到主要內容

支付網關怎麼接入網站?從零代碼到完整 API 的 4 種方式

支付網關接入方式對比:插件、易支付兼容接口、收款鏈接和 API 直連,各需要什麼、能做什麼,以及如何選擇最適合你的那一種。

發佈於 約 4 分鐘閲讀

手繪插畫:從一個網站出發的四條路徑,分別標着 plugin、epay、link 和 API,最終匯入同一個收銀台,旁邊一個指着它們的人
本文目錄
  1. 四種接入方式對比
  2. 方式一:現成插件
  3. 方式二:易支付兼容接口
  4. 方式三:收款鏈接
  5. 方式四:API 直連
  6. 如何選擇
  7. 無論哪種方式都要遵守的規則
  8. 先試再選
  9. 總結

支付網關接入,就是你的網站把買家交給支付服務商、並得知買家已付款的那套機制。它不一定意味着幾周的開發:根據你使用的系統,它可以是幾分鐘就能配置好的插件、一個貼到頁面上的鏈接,也可以是從服務端調用的 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 給你全部能力:創建訂單、查詢訂單、退款、讀取資金流水、處理拒付。一個基礎的接入只需要兩步:

  1. 創建訂單,並把買家重定向到它的 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"
  }'
  1. 驗證 Webhook,收到 payment.succeeded 時履約。

收銀台本身是託管的,所以卡號信息永遠不會到達你的服務器,見 託管收銀台是什麼。快速接入 完整演示了這個過程;在此基礎上,再加上用冪等鍵安全重試(見 冪等鍵是什麼)和錯誤處理(見 支付接口錯誤處理)。

如何選擇

  • 你的平台有插件 → 用插件。
  • 你的平台支持易支付 → 用易支付兼容接口。
  • 你只賣幾樣固定價格的東西,或者想今天就開始 → 用收款鏈接。
  • 你有自研系統,或者需要自動化處理退款和對賬 → 用 API。

這些方式可以混用:一個賬戶可以在一個網站上用插件、在另一個網站上用 API、再用收款鏈接處理賬單,每一套接入作為一個獨立的應用,有自己的密鑰,見 多個網站如何用一個商戶賬戶收款。

無論哪種方式都要遵守的規則

  • 以通知或訂單查詢為準履約,永遠不要以買家回到你的網站為準,見 return_url 和 notify_url 的區別。
  • 正式收款必須有地方接收通知。 要麼每筆訂單帶上公網 HTTPS 的 notify_url,要麼該應用有一個訂閲了 payment.succeeded 的 Webhook 端點,否則正式訂單會被拒絕。易支付訂單自帶通知地址,不受這條限制。
  • 一套系統一個應用。 每套系統有自己的密鑰、訂單號和通知,資金仍在同一個賬戶裏。
  • 測試憑證和正式憑證分開。 API 密鑰前綴(kuko_test_ / kuko_live_),或者易支付的 pid,決定了環境,兩個環境的簽名密鑰也不同,見 沙箱環境和正式環境有什麼區別。

先試再選

每種方式都可以在沙箱裏跑通,不需要等待資質審核。先完成接入,測試成功、被拒和 Webhook,再切換到正式密鑰,測試場景見 支付測試卡號大全。

總結

  • 支付網關接入可以是插件、易支付兼容接口、收款鏈接或 API 直連,最終都通向同一個託管收銀台;
  • 插件和易支付不需要寫代碼,收款鏈接不需要訂單系統,API 提供完整的控制;
  • 根據你的平台以及需要自動化的程度來選擇,也可以按應用混用多種方式;
  • 無論選哪種,都要以通知履約、給正式訂單配置接收通知的地方,並把測試和正式憑證分開。

在沙箱裏把它跑通

註冊商戶後即可申請測試密鑰,不需要等待資質審核。