Thanh toán — API + webhook

Tiền thật là việc của người khác

Khoảnh khắc app của bạn thu tiền, bạn đối mặt với mạng thẻ, 3-D Secure, quy tắc chống gian lận và hàng chục phương thức thanh toán địa phương. Đó là cả một ngành — hãy thuê, đừng tự xây.

Dàn nhân vật — bốn vai, một thanh toán

Chỉ bạn và nhà cung cấp viết code. Khách chỉ việc trả tiền; ngân hàng chỉ việc chuyển tiền.

①–③ đồng bộ (vài giây). ④ bất đồng bộ (vài phút) — và ④ là thứ bạn phải xây để tồn tại.

Nhà cung cấp đưa bạn đúng ba thứ

Mọi gateway trên thế giới đều bán gói này. Tên endpoint thay đổi; gói thì không.

Phân chia việc cho gọn

Ranh giới giữa hai cột chính là toàn bộ kiến trúc. Vượt qua nó (lưu số thẻ, tự gọi API ngân hàng) là bạn đã tự xây lại ngân hàng.

Vì sao 'không bao giờ chạm vào dữ liệu thẻ' CHÍNH là kiến trúc

PCI DSS là bộ quy định tuân thủ dành cho bất kỳ ai lưu hoặc truyền dữ liệu thẻ. Trang checkout host sẵn của nhà cung cấp gánh thay bạn phần đó — miễn phí.

Luồng thanh toán năm nhịp

Nhịp 1–3 đồng bộ, chỉ vài giây. Nhịp 4–5 bất đồng bộ, mất vài phút — nhịp 4 là thứ bạn phải xây để tồn tại.

Việc mở khóa (5) được kích hoạt bởi 4 — không bao giờ bởi redirect về trình duyệt của khách.

Tạo một thanh toán — khoảng chục dòng

Một POST HTTPS duy nhất từ app của bạn sang nhà cung cấp. Response là URL checkout — khách sang đó để trả tiền thật.

# your app: customer clicked "Pay 200,000đ / month"
import os
import requests

r = requests.post(
    "https://api.sepay.example/v1/payments",
    headers={"Authorization": "Bearer " + os.environ["SEPAY_API_KEY"]},
    json={
        "amount": 200000,        # VND, integer
        "currency": "VND",
        "order_ref": "order_8123",  # YOUR id — you'll match on it later
        "webhook_url": "https://app.example.com/webhooks/pay",
    },
)
checkout = r.json()  # -> {"url": "https://pay.sepay.example/p/a1b2c3"}

Không thấy dữ liệu thẻ đâu. Bạn gửi thứ bạn bán và nơi để báo lại. Nhà cung cấp trả về URL checkout — chứ không phải 'đã trả'.

Cái 200 không phải là tiền

Lỗi phổ biến nhất của người mới: thấy HTTP 200 từ 'tạo thanh toán' và mở khóa sản phẩm luôn. 200 nghĩa là 'đã tạo trang checkout', không phải 'khách đã trả'.

Câu trả lời của API, trực tiếp

Thứ nhà cung cấp thực sự trả về khi bạn tạo thanh toán: một 200, và một URL checkout. Đọc kỹ mã trạng thái — nó ghi 'created' (đã tạo), không phải 'paid' (đã trả).

Webhook, chính xác

Không có phép thuật: nó là một HTTPS POST đến một route của bạn — giống hệt form submission, chỉ khác người gửi là nhà cung cấp và thời điểm do họ quyết.

API vs webhook — cùng một thứ, chiếu gương

Một mẫu URL, hai chiều. Phần lớn sự nhầm lẫn trong thanh toán đến từ quên mình đang ở phía nào.

Khoảng trống async, trực quan hóa

Giữa 'khách bấm trả tiền' và 'server của bạn biết chuyện đó' là những con người thật và những ngân hàng thật. Thiết kế cho khoảng trống, chứ không phải đường đi thuận lợi.

Bên trái webhook: request/response. Bên phải webhook: thế giới vận động, bạn phản ứng.

Một sự kiện thật — nhỏ là có chủ đích

Header request còn mang chữ ký (ví dụ X-Signature) — bằng chứng nó thực sự đến từ nhà cung cấp. Body mang order_ref của chính bạn — bằng chứng đó là đơn CỦA BẠN.

{
  "event": "payment.succeeded",
  "id": "evt_9f8e7d6c",
  "created_at": "2026-10-27T03:14:09Z",
  "payment": {
    "id": "pay_a1b2c3",
    "amount": 200000,
    "currency": "VND",
    "order_ref": "order_8123",
    "method": "card"
  }
}

Mỗi trường tồn tại để handler của bạn có thể xác minh, ghép, và hành động — hoặc an toàn bỏ qua.

Endpoint webhook của bạn, đầu cuối

Năm việc: xác minh, tìm, đối chiếu, đổi trạng thái, xác nhận. Việc mở khóa nằm ở đây — không phải ở redirect về trình duyệt, thứ mà khách có thể bỏ qua.

@app.post("/webhooks/pay")
def webhook():
    if not verify_signature(request):          # 1. is it really the provider?
        return "not you", 401
    data = request.json
    order = Order.get(data["payment"]["order_ref"])  # 2. find YOUR order
    if order is None or order.total != data["payment"]["amount"]:
        return "mismatch", 400                  # 3. sanity-check the match
    mark_paid(order)                             # 4. flip state: unlock plan
    return "ok", 200                             # 5. fast 200 = "I got it"

Ngắn có chủ đích: kiểm tra, đổi trạng thái, rồi rút lui. Việc nặng (email, cấp quyền) giao cho job nền.

Hợp đồng webhook — bốn lời hứa

Tài liệu của mọi nhà cung cấp đều nói cùng bốn điều này, bằng từ khác. Phá một trong số đó là retry sẽ chất đống.

Xem một lần retry diễn ra

Đây không phải lỗi — hệ thống đang hoạt động đúng thiết kế. Cùng một sự kiện, giao hai lần, mà cơ sở dữ liệu của bạn vẫn chỉ hiện đúng một lần mở khóa.

Đối soát — sự kiện của họ, đơn của bạn

Webhook không biết gì về kinh doanh của bạn. Việc của bạn là dịch 'thanh toán X thành công' thành 'đơn Y đã trả' — một cách cẩn thận.

Idempotency — cùng sự kiện, nhiều lần, một hiệu ứng

Webhook sẽ đến hai lần: retry sau timeout, gửi trùng, hoặc chính bạn curl khi test. Handler phải an toàn để chạy bao nhiêu lần cũng được.

Cái khóa, trong sáu dòng

Hai dòng làm trọn việc: 'đã trả chưa?' và 'đã thấy sự kiện này chưa?'. Mọi thứ phía sau chỉ chạy tối đa một lần cho mỗi đơn.

@app.post("/webhooks/pay")
def webhook():
    if not verify_signature(request):
        return "not you", 401
    data = request.json
    if Event.seen(data["id"]):           # already processed this event
        return "ok", 200
    order = Order.get(data["payment"]["order_ref"])
    if order and order.status == "paid":  # already unlocked this order
        return "ok", 200
    mark_paid(order)
    Event.remember(data["id"])
    return "ok", 200

Giờ retry, gửi trùng và cả lệnh curl test của bạn đều vô hại — hiệu ứng là 'tối đa một lần' bất kể request đến bao nhiêu lần.

Bí mật — key, URL, và ranh giới

Bạn chỉ giữ đúng hai thứ nhạy cảm: API key của nhà cung cấp và việc tồn tại URL webhook của bạn. Đối xử với mỗi thứ cho đúng.

Key sống trong môi trường

Cùng một mẫu ở mọi nơi triển khai: file .env bị git bỏ qua, và code đọc nó khi chạy. Key chỉ xuất hiện đúng một nơi — trong môi trường của server.

# .env — git-ignored, lives only on the server
SEPAY_API_KEY=sk_live_9f8e7d6c5b4a3210
SEPAY_WEBHOOK_SECRET=whsec_1a2b3c4d5e6f

# app.py reads it at runtime — never hard-coded
API_KEY = os.environ["SEPAY_API_KEY"]

Tiền tố _live_ là quy ước: key test và key thật tồn tại song song theo môi trường. Một commit chứa sk_live_... là một sự cố.

Toàn bộ thanh toán trong một bức tranh

Hai mũi tên, một bước lật trạng thái. Nếu không nhớ gì khác trong chủ đề này, hãy nhớ bức tranh này.

API = bạn hỏi. Webhook = thế giới báo. Lật trạng thái = sản phẩm của bạn. Đó là thanh toán.

Năm kiểm tra trước khi có tiền thật

Chạy danh sách này vào ngày bạn đổi từ key test sang key thật. Mỗi mục kiểm tra ngăn một bug mà nếu không, bạn hoặc khách sẽ mất tiền.