跳轉到主要內容

Python 支付接入:在 Flask 或 Django 裏收款,並處理 Webhook

一步步完成 Python 支付接入:用 requests 創建訂單、跳轉收銀台、在 Flask 或 Django 裏驗證 Webhook,並且只履約一次。

發佈於 約 2 分鐘閲讀

手繪插畫:一個 Python 文件裏有 create_checkout 函數和一個 Webhook 視圖,連到託管收銀台再返回,旁邊一個人正指着它
本文目錄
  1. 準備工作
  2. 第一步:創建訂單
  3. 第二步:在 Flask 裏驗證 Webhook
  4. 第三步:只履約一次
  5. 第四步:需要時查詢訂單
  6. 第五步:在沙箱裏測試
  7. 總結

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" 等

把它用在成功頁和補償任務上,見 支付成功頁怎麼做,而不是作為履約的觸發條件。

第五步:在沙箱裏測試

  1. 創建一張訂單,在收銀台用 4242 4242 4242 4242(有效期任意未來日期、安全碼任意)付款;再用 4000 0000 0000 0002 試一次被拒。見 支付測試卡號大全。
  2. 讓視圖故意返回一次 500,確認重試的事件被正確去重。
  3. 如果驗簽失敗,用 開發者 下的發送測試回調和驗簽自檢排查。

上線時,把 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 並履約,對測試回調只確認不處理;
  • 用沙箱密鑰、測試卡和隧道測試,然後換成正式密鑰。

在沙箱裏把它跑通

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