Python 支付接入:在 Flask 或 Django 裏收款,並處理 Webhook
一步步完成 Python 支付接入:用 requests 創建訂單、跳轉收銀台、在 Flask 或 Django 裏驗證 Webhook,並且只履約一次。
Python 支付接入歸結為兩段服務端代碼:一個創建訂單並返回收銀台鏈接的函數,以及一個接收支付確認 Webhook 的視圖。銀行卡、錢包和 3D Secure 都由託管收銀台處理,所以你的 Flask 或 Django 應用從不接觸銀行卡信息,也沒有需要加固的支付表單。
這篇教程用 KukoPay 搭建一套 Python 支付接入:用 requests 創建訂單、Flask 的 Webhook 視圖(附 Django 寫法)、對原始請求體驗簽、只履約一次,以及在沙箱裏測試。
準備工作
- Python 3.9+,安裝
requests以及 Flask 或 Django。 - 在 開發者 → API 密鑰 取得的沙箱 API 密鑰(
kuko_test_…),以及同一頁面上應用的回調簽名密鑰。沙箱不需要資質審核。 - 開發期間用於 Webhook 的公網 HTTPS 地址,見 如何在本地測試 Webhook。
pip install requests flask
export KUKOPAY_API_KEY=kuko_test_...
export KUKOPAY_WEBHOOK_SECRET=...
export PUBLIC_URL=https://your-tunnel.example.com第一步:創建訂單
import os, requests
API = "https://api.kukopay.com/v1"
def create_checkout(order_id: str, amount_cents: int, subject: str) -> str:
r = requests.post(
f"{API}/orders",
headers={
"X-Api-Key": os.environ["KUKOPAY_API_KEY"],
"Idempotency-Key": f"create-{order_id}",
},
json={
"out_trade_no": order_id,
"amount": amount_cents, # 以分為單位的整數:2990 = $29.90
"currency": "USD",
"subject": subject,
"notify_url": f"{os.environ['PUBLIC_URL']}/webhooks/kukopay",
"return_url": f"{os.environ['PUBLIC_URL']}/orders/{{OUT_TRADE_NO}}/complete",
},
timeout=15,
)
body = r.json()
if not r.ok:
raise RuntimeError(f"create order failed: {body.get('error')} request_id={body.get('request_id')}")
return body["data"]["checkout_url"]把買家重定向到返回的 checkout_url。三個值得保持的習慣:
- 你的訂單 id 就是
out_trade_no。 再次創建同一張訂單會返回原訂單,所以超時後重試是安全的,見 冪等鍵是什麼。 - 金額是你的服務器算出的、以分為單位的
int。 永遠不要用float,也不要取自瀏覽器,見 支付接口為什麼用「分」傳金額。 - 出錯時記錄
request_id。 用它能在 API 日誌裏找到這次調用,見 支付接口錯誤處理。
注意 f-string 裏的雙層大括號:{{OUT_TRADE_NO}} 發出去的是字面上的佔位符,買家返回時 KukoPay 會把它替換成你的訂單號。
第二步:在 Flask 裏驗證 Webhook
import hashlib, hmac, json, time
from flask import Flask, request, abort
app = Flask(__name__)
def verify(raw: bytes, header: str, secret: str) -> bool:
t, sigs = None, []
for item in header.split(","):
k, _, v = item.strip().partition("=")
if k == "t":
t = v
elif k == "v1":
sigs.append(v)
if not t or not sigs or abs(time.time() - int(t)) > 300:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(expected, s) for s in sigs)
@app.post("/webhooks/kukopay")
def kukopay_webhook():
raw = request.get_data() # 原始字節,在任何 JSON 解析之前
if not verify(raw, request.headers.get("X-KukoPay-Signature", ""), os.environ["KUKOPAY_WEBHOOK_SECRET"]):
abort(400)
event = json.loads(raw)
if event.get("test"):
return "", 200 # 測試回調:確認收到,永不履約
handle_event(event)
return "", 200對 request.get_data()——收到的原始字節——驗簽,而不是對重新序列化的 request.json 驗簽。收集所有 v1:密鑰輪換期間請求頭裏會有兩個。見 Webhook 驗簽怎麼做。
Django 裏的同一個視圖
from django.http import HttpResponse, HttpResponseBadRequest
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_POST
@csrf_exempt # 這裏由簽名代替 CSRF 校驗
@require_POST
def kukopay_webhook(request):
raw = request.body
if not verify(raw, request.headers.get("X-KukoPay-Signature", ""), os.environ["KUKOPAY_WEBHOOK_SECRET"]):
return HttpResponseBadRequest()
event = json.loads(raw)
if not event.get("test"):
handle_event(event)
return HttpResponse(status=200)第三步:只履約一次
def handle_event(event: dict) -> None:
with db.transaction():
if not db.insert_event_if_absent(event["id"]): # 事件 id 上有唯一約束
return # 已經處理過
if event["type"] == "payment.succeeded":
order = event["data"]["object"]
db.mark_paid(order["out_trade_no"], trade_no=order["trade_no"], amount=order["amount"])
queue.enqueue("fulfil", order["out_trade_no"])在同一個事務裏記錄事件 id 和狀態變更,用你自己的訂單核對金額,並把耗時的工作交給隊列(Celery、RQ),讓視圖在 10 秒內返回。見 支付回調冪等處理。
第四步:需要時查詢訂單
def order_status(out_trade_no: str) -> str:
r = requests.get(f"{API}/orders/{out_trade_no}",
headers={"X-Api-Key": os.environ["KUKOPAY_API_KEY"]}, timeout=15)
return r.json()["data"]["status"] # "pending"、"paid"、"expired"、"failed" 等把它用在成功頁和補償任務上,見 支付成功頁怎麼做,而不是作為履約的觸發條件。
第五步:在沙箱裏測試
- 創建一張訂單,在收銀台用
4242 4242 4242 4242(有效期任意未來日期、安全碼任意)付款;再用4000 0000 0000 0002試一次被拒。見 支付測試卡號大全。 - 讓視圖故意返回一次
500,確認重試的事件被正確去重。 - 如果驗簽失敗,用 開發者 下的發送測試回調和驗簽自檢排查。
上線時,把 kuko_test_ 密鑰和沙箱簽名密鑰換成同一個應用在正式環境的值,代碼不用改。同樣的流程用 JavaScript 寫,見 Node.js 支付接入。
總結
- Python 支付接入需要一個創建訂單並返回
checkout_url的函數,以及一個 Webhook 視圖; - 用
requests創建訂單,以你的訂單 id 作為out_trade_no,傳整數金額和Idempotency-Key; - 對原始請求體驗證
X-KukoPay-Signature——Flask 用request.get_data(),Django 用request.body——任意一個v1匹配即可; - 在同一個事務裏記錄事件 id 並履約,對測試回調只確認不處理;
- 用沙箱密鑰、測試卡和隧道測試,然後換成正式密鑰。
在沙箱裏把它跑通
註冊商戶後即可申請測試密鑰,不需要等待資質審核。