SILVERCLOUD / Bài viết kỹ thuật
Xác nhận thanh toán đáng tin cậy: checklist phía server cho app và website
Khách bấm Thanh toán, thấy dấu tích xanh rồi tắt app. Đơn đã được trả tiền chưa? Có lẽ rồi, nhưng với tiền thì “có lẽ” là chưa đủ. Dấu tích chỉ cho biết một thiết bị đã đi hết một luồng màn hình. Tiền có thật sự chuyển hay không thì nhà cung cấp thanh toán mới biết, và server của bạn phải hỏi thẳng nhà cung cấp, qua một kênh không ai giả mạo được.
Checklist này đi qua các trạng thái thanh toán, cách xác nhận phía server, thử lại an toàn, hoàn tiền, đối soát và kiểm thử, áp dụng cho thẻ, ví điện tử lẫn chuyển khoản QR.
Màn hình thành công chưa phải là xác nhận
Trả tiền xong, khách được đưa về website hoặc app của bạn, thường kèm tham số kiểu ?status=success&order=1042. Coi đó là bằng chứng thì hỏng theo ba cách:
- Ai cũng sửa được. Đổi
failedthànhsuccesstrên trình duyệt chỉ mất vài giây. - Có thể không bao giờ tải. Khách đóng tab, điện thoại mất sóng, hoặc app ngân hàng không quay lại; giao dịch thành công mà server của bạn không hề hay biết.
- Có thể đến trước tiền. Một số phương thức, nhất là chuyển khoản, còn ở trạng thái chờ sau khi khách đã làm xong phần của mình.
Trang trả về nên hiện “Đang xác nhận thanh toán” và hỏi server của chính bạn, nơi chỉ tin nguồn đã kiểm chứng. Phía client không bao giờ được quyết định đơn đã thanh toán.
Các trạng thái của một giao dịch
Hãy mô hình hoá giao dịch rõ ràng, thay vì chỉ một cờ paid:
- Đã tạo: đã đăng ký với nhà cung cấp, khách chưa trả.
- Đang chờ: khách đã thao tác hoặc tiền đang trên đường chuyển; kết quả chưa chốt.
- Thành công: nhà cung cấp xác nhận khoản tiền.
- Thất bại: bị từ chối, bị huỷ hoặc bị chặn.
- Hết hạn: hết thời gian thanh toán mà không có kết quả.
- Hoàn tiền một phần và hoàn tiền toàn phần: tiền được trả lại sau khi đã thành công, một phần hoặc toàn bộ.
Với thẻ còn có trạng thái đã chuẩn chi nhưng chưa capture, và về sau là khiếu nại (dispute). Hãy viết các bước chuyển hợp lệ thành code: đã tạo có thể sang đang chờ; đã tạo hoặc đang chờ có thể sang thành công, thất bại hoặc hết hạn; thành công có thể sang hoàn tiền một phần hoặc toàn phần, và giao dịch đã hoàn một phần vẫn có thể hoàn thêm; không gì quay về đã tạo hay đang chờ. Mọi thay đổi khác hoặc là lỗi, hoặc là ca cần người xem.
Xác nhận phía server, từ nguồn kiểm chứng được
Có hai nguồn đáng tin, và một bản tích hợp chắc chắn dùng cả hai.
Webhook có chữ ký. Nhà cung cấp gọi vào endpoint của bạn khi có sự kiện, và phần lớn nhà cung cấp ký mỗi request bằng một khoá bí mật dùng chung: thường là HMAC-SHA256 trên raw body, hay kèm dấu thời gian. Handler của bạn cần:
- Đọc raw body đúng như nhận được. Parse JSON rồi serialize lại có thể đổi khoảng trắng, cách escape hoặc thứ tự khoá, và chữ ký sẽ không còn khớp.
- Tự tính HMAC rồi so với header bằng phép so sánh thời gian hằng (constant-time). Phép so sánh chuỗi thông thường dừng ngay ở ký tự sai đầu tiên, và chênh lệch thời gian đó có thể làm lộ thông tin về chữ ký đúng.
- Từ chối dấu thời gian nằm ngoài một khoảng ngắn, thường là năm phút, để request có bị bắt lén cũng không phát lại được về sau; còn nếu bị phát lại ngay trong khoảng đó thì bước khử trùng theo mã sự kiện sẽ chặn.
- Đối chiếu số tiền, loại tiền và mã đơn với đơn bạn đã tạo. Chữ ký hợp lệ chứng minh ai gửi tin, không chứng minh khách đã trả đúng số tiền cho đúng đơn. Lưu số tiền dạng số nguyên theo đơn vị nhỏ nhất của loại tiền, không dùng số thực dấu phẩy động.
API của nhà cung cấp. Server tra giao dịch theo ID bằng khoá bí mật của bạn. Cách này bù cho webhook đến muộn hoặc thất lạc; có đội còn coi mọi webhook chỉ là tín hiệu để đi lấy trạng thái hiện tại.
Khoá API và khoá ký webhook nằm trên server, không nằm trong app hay repository, và phải đổi được mà không cần dừng hệ thống.
Idempotency: một sự kiện đến hai lần thì không đổi gì
Phần lớn nhà cung cấp gửi webhook theo kiểu “ít nhất một lần”: endpoint của bạn hết thời gian chờ hoặc trả lỗi thì sự kiện được gửi lại, có khi nhiều lần. Trùng lặp là chuyện bình thường, nên phần xử lý phải idempotent, tức chạy lại bao nhiêu lần kết quả vẫn như một.
- Khử trùng theo mã sự kiện. Lưu mã sự kiện đã xử lý với ràng buộc unique, để lần gửi lặp không đổi được gì.
- Một giao dịch DB, một lần cập nhật. Ghi mã sự kiện và đổi trạng thái đơn trong cùng một giao dịch cơ sở dữ liệu; có lỗi thì cả hai cùng rollback và lần thử lại bắt đầu sạch. Đặt điều kiện cho câu cập nhật (
WHERE status = 'pending'), để webhook và lượt tra API đến cùng lúc không thể cùng xử lý một đơn hai lần. - Khoá idempotency khi tạo giao dịch và hoàn tiền. Nếu nhà cung cấp hỗ trợ, hãy sinh khoá từ mã lần thanh toán của chính bạn; lần thử lại sau khi hết thời gian chờ sẽ nhận lại kết quả cũ thay vì trừ tiền lần hai. Nếu không hỗ trợ, hãy lưu bản ghi của bạn với một mã tham chiếu duy nhất trước, rồi tra mã đó trước khi thử lại.
- Sự kiện đến sai thứ tự. Thứ tự gửi thường không được bảo đảm; sự kiện thành công có thể đến sau sự kiện hoàn tiền. Hãy xử lý theo bảng chuyển trạng thái chứ đừng ghi đè theo sự kiện đến sau cùng, và khi còn nghi thì lấy trạng thái hiện tại.
- Backoff. Thử lại khi hết thời gian chờ, lỗi kết nối, phản hồi 429 và 5xx, với backoff luỹ thừa, jitter và giới hạn số lần. Không thử lại lỗi dữ liệu không hợp lệ.
- Hết thời gian chờ nghĩa là chưa rõ, không phải thất bại. Tiền có thể đã bị trừ; hãy tra lại để chốt.
- Hết hạn theo lịch. Một job tìm các giao dịch còn chờ quá hạn, hỏi lại nhà cung cấp, rồi mới đánh dấu hết hạn. Khoản thành công đến sau khi đã hết hạn, chuyện vẫn xảy ra với chuyển khoản, được đưa vào hàng soát xét hoặc hoàn tiền theo quy tắc đã thống nhất từ trước.
Trả lời webhook thật nhanh: lưu, commit, trả 2xx, còn việc chậm như gửi email hay giao hàng thì đưa vào hàng đợi. Handler chậm gây hết thời gian chờ, và hết thời gian chờ lại sinh thêm bản trùng.
Viết thành code thì trông thế này
Một handler tối giản bằng TypeScript cho Node.js và PostgreSQL. Tên header, cách mã hoá chữ ký và chuỗi được ký khác nhau tuỳ nhà cung cấp; còn khung xử lý thì giữ nguyên.
import { createHmac, timingSafeEqual } from "node:crypto";
import { Pool } from "pg";
const pool = new Pool(); // reads the PG* environment variables
const SECRET = process.env.PAYMENT_WEBHOOK_SECRET!; // server-side only, never in the app
export async function handlePaymentWebhook(req: Request): Promise<Response> {
const raw = Buffer.from(await req.arrayBuffer()); // the exact bytes, before any JSON parsing
const timestamp = req.headers.get("x-signature-timestamp") ?? "";
const received = Buffer.from(req.headers.get("x-signature") ?? "", "hex");
const expected = createHmac("sha256", SECRET).update(`${timestamp}.`).update(raw).digest();
const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300; // Unix seconds, 5 minutes
if (!fresh || received.length !== expected.length || !timingSafeEqual(received, expected)) {
return new Response("invalid signature", { status: 400 });
}
const event = JSON.parse(raw.toString("utf8"));
const db = await pool.connect();
try {
await db.query("BEGIN");
// event_id is the primary key: a repeated delivery inserts nothing.
const inserted = await db.query(
"INSERT INTO processed_events (event_id) VALUES ($1) ON CONFLICT DO NOTHING", [event.id]);
if (inserted.rowCount === 1 && event.type === "payment.succeeded") {
// Only pending -> paid, and only if amount and currency match the order.
const paid = await db.query(
`UPDATE orders SET status = 'paid', paid_at = now()
WHERE id = $1 AND status = 'pending' AND amount = $2 AND currency = $3`,
[event.data.order_id, event.data.amount, event.data.currency]);
if (paid.rowCount === 0) await db.query("INSERT INTO payment_review (event_id) VALUES ($1)", [event.id]);
}
await db.query("COMMIT");
return new Response("ok");
} catch {
await db.query("ROLLBACK");
return new Response("retry later", { status: 500 }); // the provider retries
} finally {
db.release();
}
}Nếu không có đơn đang chờ nào khớp (đã thanh toán, đã hết hạn, hoặc lệch số tiền), sự kiện được đưa vào bảng soát xét thay vì biến mất.
Hoàn tiền, đối soát và dấu vết kiểm toán
Hoàn tiền là bản ghi riêng gắn với giao dịch, có trạng thái riêng: lệnh hoàn tiền cũng có thể đang chờ hoặc thất bại. Tổng các lần hoàn một phần không bao giờ được vượt số tiền đã thu của giao dịch. Gửi yêu cầu hoàn tiền kèm khoá idempotency, và chỉ đổi trạng thái đơn khi nhà cung cấp xác nhận.
Đối soát hằng ngày bắt những gì các lớp trên bỏ sót. Lấy báo cáo giao dịch hoặc báo cáo quyết toán ngày hôm trước của nhà cung cấp, ghép từng dòng với bản ghi của bạn theo mã giao dịch phía nhà cung cấp, rồi so số tiền, loại tiền và trạng thái. Các kiểu lệch hay gặp:
- Nhà cung cấp ghi đã trả, hệ thống của bạn vẫn chờ: webhook thất lạc, và một khách đã trả tiền mà vẫn đang đợi.
- Hệ thống của bạn ghi đã trả, nhà cung cấp không có: lỗi hoặc gian lận, loại cần xử lý gấp nhất.
- Lệch số tiền hoặc trạng thái: hoàn tiền một phần chưa ghi nhận, hoặc nhầm giữa số tiền gộp, phí và số thực nhận.
Mỗi khoản lệch vào hàng đợi chênh lệch, có người phụ trách và ghi chú cách xử lý; không sửa lặng lẽ. Để ý giờ chốt của báo cáo: giao dịch sát nửa đêm có thể rơi vào hai ngày khác nhau ở hai bên.
Dấu vết kiểm toán. Giữ mọi webhook thô kèm header và kết quả kiểm chữ ký để phát lại được, cùng lịch sử đổi trạng thái chỉ ghi thêm (append-only): từ trạng thái nào, sang trạng thái nào, lúc nào, do sự kiện, job hay người nào. Không bao giờ ghi khoá bí mật hay số thẻ đầy đủ vào log; khi dùng trang thanh toán hoặc ô nhập thẻ nhúng của nhà cung cấp, số thẻ không bao giờ chạm tới server của bạn.
Cảnh báo cần bật khi chữ ký sai tăng đột biến, xử lý webhook lỗi, giao dịch kẹt ở trạng thái chờ, hoàn tiền thất bại, đối soát lệch, hoặc tỉ lệ thành công tụt xuống.
Kiểm thử cả đường hỏng, không chỉ đường suôn sẻ
Dùng sandbox hoặc chế độ test của nhà cung cấp với khoá thử nghiệm, rồi:
- Phát lại webhook. Lưu sự kiện sandbox thật làm fixture; gửi một sự kiện hai lần, đảo thứ tự, sửa một byte trong body, dùng dấu thời gian cũ.
- Cố tình gây lỗi. Dừng tiến trình sau khi commit nhưng trước khi trả 2xx: nhà cung cấp gửi lại, và không được có gì xảy ra hai lần. Ngắt cơ sở dữ liệu một phút. Thêm độ trễ vào lời gọi tới nhà cung cấp cho tới khi timeout của bạn kích hoạt.
- Dùng sai phía client. Bấm Thanh toán hai lần liên tiếp, đóng trình duyệt trước khi chuyển hướng, mở URL trả về với tham số giả.
Checklist trước khi chạy thật
- Trạng thái đã thanh toán chỉ đến từ webhook đã xác minh hoặc lượt tra API phía server.
- Chữ ký được kiểm trên raw body bằng so sánh thời gian hằng; dấu thời gian cũ bị từ chối.
- Số tiền, loại tiền và mã đơn được đối chiếu với đơn.
- Mã sự kiện là duy nhất; bản trùng trả 2xx và không gây tác dụng phụ.
- Bản ghi sự kiện và việc đổi trạng thái commit trong cùng một giao dịch DB, với câu cập nhật có điều kiện.
- Tạo giao dịch và hoàn tiền đều dùng khoá idempotency, hoặc tra theo mã tham chiếu của bạn.
- Bước chuyển trạng thái được định nghĩa trong code; sự kiện đến muộn không kéo đơn lùi lại.
- Endpoint webhook trả lời trong thời hạn của nhà cung cấp; việc chậm đưa vào hàng đợi.
- Lời gọi ra ngoài có timeout và thử lại có giới hạn, với backoff và jitter.
- Giao dịch chờ được cho hết hạn theo lịch sau khi tra trạng thái; thành công đến muộn có đường xử lý rõ ràng.
- Hoàn tiền một phần không thể vượt số tiền đã thu.
- Đối soát chạy hằng ngày, mỗi khoản lệch có người phụ trách.
- Webhook thô và lịch sử trạng thái được lưu giữ; log không chứa khoá bí mật hay số thẻ đầy đủ.
- Cảnh báo phủ chữ ký sai, lỗi xử lý, giao dịch kẹt và lệch đối soát.
silvercloud là đội phát triển phần mềm thuê ngoài. Chúng tôi xây phần việc này vào app và website cho doanh nghiệp đối tác, từ checkout, webhook đến hoàn tiền và đối soát, xây cả hệ thống cổng thanh toán theo yêu cầu của đối tác, rồi bàn giao để đội của đối tác vận hành. Nếu bạn đang chuẩn bị tích hợp thanh toán, hãy gửi brief cho chúng tôi tại silvercloud.city.