Cụm bài Tích hợp cổng thanh toán: 1. Redirect, chữ ký và IPN · 2. IPN tới muộn, đối soát và failure mode
Tích hợp “chạy được” rồi vẫn còn IPN tới muộn, IPN không tới, và số liệu lệch với cổng. Đọc xong, bạn xử lý được IPN muộn, thiết kế được đối soát, và test được mọi failure mode. Nên đọc trước: phần 1, và bài booking và ledger cho phần sổ cái.
Sơ đồ tóm tắt:
flowchart TD
A["IPN từ cổng"] --> C["apply idempotent"]
B["Job querydr định kỳ"] --> C
C --> D["Ghi SUCCEEDED"]
D --> E{"Booking còn giữ chỗ?"}
E -->|"Còn"| F["Booking PAID"]
E -->|"Đã nhả"| G{"Còn ghế cùng hạng?"}
G -->|"Có"| F
G -->|"Không"| H["REFUND_PENDING, hoàn tiền"]
I["Đối soát hằng ngày"] --> J["FULL JOIN sao kê và payment"]
J --> K["5 loại, OURS_ONLY nặng nhất"]
1. Case study: IPN tới sau khi đã nhả chỗ
Ý chính: không bao giờ bỏ qua IPN thành công tới muộn. Ghi nhận tiền, rồi giữ lại chỗ hoặc hoàn tiền; và đặt khoảng thời gian để trường hợp này hiếm.
Nhắc lại phần 1: payment attempt và hàm apply
Backend tạo booking PENDING_PAYMENT và một payment attempt (lần thử thanh toán) PENDING. Mỗi lần thử có một txn_ref, mỗi booking tối đa một lần thử đang mở. URL được ký bằng HMAC-SHA512, IPN được nhận bằng một handler idempotent. Hàm apply(result) chạy trong một transaction và dùng conditional update (UPDATE kèm điều kiện trạng thái cũ): payment từ PENDING/EXPIRED sang SUCCEEDED/FAILED, booking từ PENDING_PAYMENT sang PAID. Câu nào cập nhật 0 dòng nghĩa là đã xử lý rồi hoặc trạng thái không còn hợp lệ.
Bối cảnh. Booking giữ ghế 15 phút. Khách mở trang cổng ở phút 13, nhập OTP chậm, bị trừ tiền ở phút 16. Job hết hạn đã nhả ghế ở phút 15, người khác vừa mua ghế đó. IPN thành công tới ở phút 16.
Ràng buộc. Tiền đã trừ thật, không được bỏ qua IPN. Khách không mất tiền, không hai người cùng một ghế.
Thiết kế chọn: kết hợp cả ba lựa chọn.
- Ngăn từ đầu:
vnp_ExpireDatengắn hơn hạn giữ chỗ (URL 15 phút, ghế 20 phút). Job hết hạn không nhả booking còn paymentPENDINGchưa quá hạn cộng khoảng đệm. Giảm mạnh xác suất nhưng không về 0 (cổng chậm, đồng hồ lệch). - Hỏi trước khi nhả: booking còn payment mở thì job gọi API truy vấn giao dịch; chỉ nhả khi cổng xác nhận chưa trả.
- IPN muộn vẫn tới: ghi payment
SUCCEEDED, thử giữ lại chỗ (còn ghế cùng hạng thì giữ và chuyển bookingPAID). Không được thì chuyển payment sangREFUND_PENDING, hoàn tiền tự động, báo khách.
(1) và (2) làm nó hiếm, (3) xử lý đúng khi nó vẫn xảy ra. Job hết hạn có điều kiện “không còn payment đang mở”:
UPDATE booking b
SET status = 'EXPIRED', version = version + 1, updated_at = now()
WHERE b.status = 'PENDING_PAYMENT' AND b.expires_at < now()
AND NOT EXISTS (
SELECT 1 FROM payment p
WHERE p.booking_id = b.booking_id AND p.status = 'PENDING'
AND p.expires_at > now() - interval '5 minutes') -- đệm cho cổng xử lý chậm
RETURNING booking_id;
Nhánh hoàn tiền của apply và kết quả chạy thử trên PostgreSQL 16
Nhánh của apply khi booking không còn ở PENDING_PAYMENT (UPDATE booking cập nhật 0 dòng):
UPDATE payment SET status = 'REFUND_PENDING', updated_at = now()
WHERE txn_ref = :txnRef AND status = 'SUCCEEDED';
-- + chèn outbox "hoàn tiền" kèm idempotency key = txn_ref, và thông báo cho khách
SQL trong bài đã chạy thử trên PostgreSQL 16:
- Booking quá hạn nhưng còn payment
PENDINGhạn tới 2 phút nữa: không bị hết hạn (0 dòng). - IPN thành công cho booking đã
EXPIRED: payment điEXPIRED → SUCCEEDED → REFUND_PENDINGtrong một transaction, booking giữ nguyênEXPIRED.
2. Đối soát
Ý chính: đối soát (reconciliation) là làm cho ba nguồn khớp nhau: trạng thái trong DB, sổ cái, và dữ liệu của cổng. Có hai nhịp: truy vấn giao dịch vài phút một lần, và so sao kê mỗi ngày.
2.1. Gần thời gian thực: truy vấn giao dịch
Job chạy mỗi vài phút:
- Lấy payment
PENDINGđã quáexpires_at, hoặc khách đã quay về mà IPN chưa tới. - Gọi API truy vấn của cổng (VNPay:
querydr, server-to-server, chữ ký riêng theo thứ tự trường cố định), theo lô nhỏ, tôn trọng giới hạn tần suất. - Đưa kết quả qua cùng hàm
applynhư IPN (phần 1). Cổng không thấy hoặc báo chưa trả thì payment sangEXPIRED; lỗi mạng thì để lần sau.
2.2. Hằng ngày: đối chiếu file với DB và sổ cái
Nạp sao kê (statement) theo ngày của cổng (file hoặc API) vào bảng tạm gateway_statement, rồi FULL JOIN với payment thành công cùng ngày theo giờ Việt Nam để thấy chỗ thiếu ở cả hai phía:
WITH g AS (
SELECT * FROM gateway_statement WHERE statement_date = DATE '2026-11-18'
), ours AS (
SELECT * FROM payment
WHERE status IN ('SUCCEEDED', 'REFUND_PENDING', 'REFUNDED')
AND paid_at >= TIMESTAMPTZ '2026-11-18 00:00+07' AND paid_at < TIMESTAMPTZ '2026-11-19 00:00+07'
)
SELECT coalesce(g.txn_ref, ours.txn_ref) AS txn_ref,
CASE
WHEN ours.txn_ref IS NULL AND p.payment_id IS NULL THEN 'UNKNOWN_TO_US'
WHEN ours.txn_ref IS NULL THEN 'NOT_PAID_HERE'
WHEN g.txn_ref IS NULL THEN 'OURS_ONLY'
WHEN ours.amount <> g.amount THEN 'AMOUNT_MISMATCH'
ELSE 'MATCHED'
END AS result
FROM g
FULL JOIN ours ON ours.txn_ref = g.txn_ref
LEFT JOIN payment p ON p.txn_ref = g.txn_ref;
Chạy thử trên dữ liệu mẫu ra đủ năm loại:
| Kết quả | Nghĩa | Xử lý |
|---|---|---|
MATCHED |
Khớp | Không làm gì |
NOT_PAID_HERE |
Cổng đã thu, mình còn PENDING/EXPIRED |
IPN và truy vấn đều lỡ: chạy apply bằng dữ liệu sao kê, điều tra |
UNKNOWN_TO_US |
Cổng có giao dịch mình không hề tạo | Nghiêm trọng: sai merchant, lộ khoá, hoặc môi trường test trỏ nhầm; báo động |
OURS_ONLY |
Mình ghi thành công, cổng không có | Nghiêm trọng nhất: có thể đã xuất vé không thu tiền; kiểm tra với cổng ngay |
AMOUNT_MISMATCH |
Lệch số tiền | Lỗi đơn vị hoặc bug; khoá đơn, điều tra |
Đối soát tiền về (settlement). Cổng chuyển tiền vào ngân hàng sau khi trừ phí, thường T+1. Ghi SETTLEMENT vào sổ cái (Nợ ngân hàng, Nợ phí, Có tài khoản tiền cổng giữ hộ, tức clearing account), rồi kiểm số dư tài khoản này về đúng phần chưa chuyển. Cách ghi ở bài booking và ledger.
3. Test trên sandbox
Ý chính: sandbox chỉ để chạy thử bằng tay; CI tự ký IPN bằng khoá test và gọi thẳng endpoint, mỗi failure mode một kịch bản BDD chạy trên Testcontainers PostgreSQL.
- IPN cần URL công khai: máy dev không nhận được. Dùng tunnel (cloudflared, ngrok) hoặc staging có domain thật.
- Không phụ thuộc sandbox trong CI: sandbox chậm, có lúc bảo trì.
- Tài khoản test: cổng cấp
vnp_TmnCodevà hash secret riêng, cùng thẻ test (VNPay: thẻ nội địa NCB, OTP cố định; lấy thông tin hiện hành trên trang sandbox). - Testcontainers PostgreSQL (chạy PostgreSQL thật trong Docker khi test) cho các kịch bản, vì chúng phụ thuộc hành vi thật của conditional update và unique constraint.
Sáu kịch bản BDD cho IPN
- Given payment
PENDING3.000.000đ, When IPN thành công hợp lệ tới, Then paymentSUCCEEDED, bookingPAIDversion 2, sổ cái cân, phản hồi00. - Given IPN trên đã xử lý, When đúng IPN đó tới lần nữa, Then không dòng nào đổi, phản hồi
02. - Given bất kỳ, When IPN có chữ ký sai, Then không dòng nào đổi, phản hồi
97, callback được lưu vớisignature_ok = false. - Given payment 3.000.000đ, When IPN báo
vnp_Amount = 290000000, Then phản hồi04, có cảnh báo. - Given booking đã
EXPIRED, When IPN thành công tới, Then paymentREFUND_PENDING, có outbox hoàn tiền. - Given hai IPN giống nhau tới đồng thời, When xử lý song song, Then đúng một lần chuyển trạng thái, một bộ bút toán.
4. Bảng failure mode
Ý chính: ba cơ chế xử lý gần hết sự cố: conditional update, job truy vấn giao dịch, và trạng thái REFUND_PENDING.
| Sự cố | Hậu quả nếu bỏ qua | Cách xử lý |
|---|---|---|
| IPN không tới | Khách đã trả, booking chờ rồi hết hạn | Job truy vấn giao dịch; đối soát file hằng ngày |
| IPN tới nhiều lần | Ghi sổ, xuất vé hai lần | Conditional update theo trạng thái, unique gateway_txn_no, trả 02 |
| IPN tới đồng thời | Hai luồng cùng qua kiểm tra | Conditional update làm trọng tài, unique constraint là lưới cuối |
| IPN tới sau khi hết hạn | Khách mất tiền hoặc bán trùng ghế | Mục 1: hạn URL ngắn hơn hạn giữ chỗ, hỏi trước khi nhả, REFUND_PENDING |
| Return URL tới trước IPN | Màn hình báo thất bại sai | Frontend hỏi backend, chấp nhận “đang xác nhận” |
| Bấm thanh toán hai lần, hai tab | Hai lần thử, có thể cùng thành công | Một payment PENDING mỗi booking (trả lại URL cũ); lần thành công thứ hai → REFUND_PENDING |
Sáu sự cố còn lại: trình duyệt, chữ ký, số tiền, DB, cổng, hoàn tiền
| Sự cố | Hậu quả nếu bỏ qua | Cách xử lý |
|---|---|---|
| Khách đóng trình duyệt | Không có return URL | Không sao: IPN và truy vấn vẫn cập nhật; email xác nhận qua outbox |
| Chữ ký sai | Gian lận hoặc bug encode | Trả 97, lưu callback, cảnh báo khi tỉ lệ tăng |
| Lệch số tiền | Thu thiếu hoặc thừa | Trả 04, khoá đơn, một chỗ đổi đơn vị duy nhất |
| DB chết lúc nhận IPN | Mất kết quả | Trả 99 để cổng gửi lại; truy vấn giao dịch vá phần thiếu |
| Cổng chết lúc tạo URL | Khách không trả được | Timeout ngắn, báo thử lại, không giữ chỗ quá hạn vì lỗi này |
| Hoàn tiền thất bại | Khách không nhận lại tiền | REFUND_PENDING với retry có idempotency key, cảnh báo khi quá N giờ |
Bài tập
Bài 1: Viết truy vấn đối soát
Đề: cho bảng gateway_statement(statement_date, txn_ref, gateway_txn_no, amount, status) nạp từ file của cổng. Viết truy vấn phân loại mọi giao dịch trong ngày thành khớp, mình thiếu, cổng thiếu, lệch tiền, và giao dịch lạ.
Lời giải Bài 1
Câu SQL ở mục 2.2. Điểm cần nghĩ:
- Lọc ngày theo giờ Việt Nam:
paid_atlàtimestamptz, ranh giới ngày là 00:00+07. FULL JOINđể thấy cả hai phía thiếu.- Tách “mình có payment nhưng chưa thành công” khỏi “mình không có payment nào”, vì cách xử lý khác hẳn.
- Giao dịch quanh nửa đêm có thể nằm ở hai file; so thêm file ngày kế tiếp trước khi kết luận
OURS_ONLY.
Bài 2: Thiết kế job truy vấn giao dịch
Đề: mô tả job “vá” các payment PENDING không nhận được IPN, an toàn khi chạy nhiều instance và không vượt giới hạn tần suất của cổng.
Lời giải Bài 2
- Mỗi phút, lấy lô 50 payment
PENDINGcóexpires_at < now() - interval '2 minutes'bằngFOR UPDATE SKIP LOCKED(bỏ qua dòng instance khác đang khoá, nên các instance chia nhau lô; xem bài giữ ghế). - Thêm cột
last_queried_at, cập nhật trong transaction chọn lô, để lần chạy sau không lấy lại ngay. - Gọi API truy vấn sau khi commit transaction chọn lô: không giữ khoá khi gọi mạng.
- Đưa kết quả vào hàm
applydùng chung. - Rate limiter phía mình (token bucket) theo hạn mức cổng.
- Quá N lần không có kết quả thì cảnh báo cho người xử lý.
Ghi nhớ
- Giải thích được vì sao IPN tới muộn vẫn phải ghi
SUCCEEDED, và hai hướng xử lý sau đó. - Biết ba cách làm IPN muộn hiếm: hạn URL ngắn hơn hạn giữ chỗ, đệm trong job hết hạn, hỏi cổng trước khi nhả.
- Viết lại được truy vấn đối soát
FULL JOINvà kể năm loại kết quả, loại nào nghiêm trọng nhất. - Biết vì sao lọc ngày phải dùng khoảng
+07chứ không::date. - Kể được cách test IPN trong CI không cần sandbox.
Câu hỏi phỏng vấn
Junior
Đối soát thanh toán là gì, vì sao cần dù đã có IPN?
Đối soát là so dữ liệu của mình (payment, sổ cái) với dữ liệu của cổng (sao kê, tiền về) để tìm chỗ lệch. Cần vì IPN có thể mất, tới muộn, hoặc code có bug.
Chỉ đối soát mới phát hiện được “cổng đã thu mà mình chưa ghi” hay “mình ghi thành công mà cổng không có”. Không có nó, sai lệch chỉ lộ ra khi khách khiếu nại hoặc khi kế toán khoá sổ.
Mid
Vì sao hạn của URL thanh toán phải ngắn hơn hạn giữ chỗ?
Để cổng tự từ chối thanh toán trước khi ghế bị nhả, nhờ đó IPN tới muộn trở nên hiếm.
Nếu bằng nhau hoặc dài hơn, khách có thể trả ở phút cuối trong khi job đã nhả ghế cho người khác. Đặt vnp_ExpireDate ngắn hơn (URL 15 phút, ghế 20 phút) và cho job hết hạn chừa khoảng đệm cho payment còn mở.
Job truy vấn giao dịch chạy trên nhiều instance thế nào cho an toàn?
Chia lô bằng FOR UPDATE SKIP LOCKED, commit trước khi gọi mạng, và đưa kết quả qua hàm apply idempotent.
Mỗi lần chạy lấy một lô payment PENDING quá hạn, cập nhật last_queried_at rồi commit (không giữ khoá khi chờ cổng). Gọi API truy vấn qua rate limiter theo hạn mức cổng. Hai instance có lỡ cùng xử lý một payment thì conditional update vẫn chỉ cho một lần chuyển trạng thái.
Settlement là gì và ghi vào sổ cái thế nào?
Là lúc cổng chuyển tiền đã thu về ngân hàng của merchant, thường T+1, sau khi trừ phí và các khoản đã hoàn.
Ghi một giao dịch nhiều chân: Nợ ngân hàng phần thực nhận, Nợ chi phí phí cổng, Có tài khoản tiền cổng giữ hộ. Sau settlement, số dư tài khoản giữ hộ phải bằng phần chưa được chuyển; lệch là tín hiệu cần đối soát.
Senior
IPN thành công tới sau khi booking đã hết hạn và ghế đã bán cho người khác. Bạn xử lý thế nào?
Ghi nhận payment thành công vì tiền là thật, thử giữ ghế khác cùng hạng với giá đã chốt; không được thì REFUND_PENDING và hoàn tự động.
Báo khách trong cả hai trường hợp. Quan trọng hơn là làm nó hiếm: hạn URL ngắn hơn hạn giữ chỗ, job hết hạn không nhả booking còn payment đang mở, và hỏi cổng trước khi nhả. Có metric và cảnh báo cho số REFUND_PENDING.
Thiết kế đối soát với cổng thanh toán thế nào?
Hai nhịp: job truy vấn giao dịch gần thời gian thực, và so sao kê hằng ngày; sau đó đối soát tiền về.
- Gần thời gian thực: truy vấn payment quá hạn chưa có kết quả, dùng chung hàm idempotent với IPN.
- Hằng ngày: nạp sao kê, FULL JOIN với payment thành công theo ngày giờ Việt Nam, phân loại khớp, mình thiếu, cổng thiếu, lệch tiền, giao dịch lạ; mỗi loại có quy trình xử lý.
- Tiền về: ghi settlement vào sổ cái, kiểm số dư tài khoản tiền cổng giữ hộ.
Làm sao test tích hợp thanh toán mà không phụ thuộc sandbox của cổng trong CI?
Tự ký bộ tham số IPN bằng khoá test và gọi thẳng endpoint; API của cổng đặt sau interface và giả lập.
- Test chữ ký bằng bộ tham số và chữ ký mẫu cố định.
- Integration test với Testcontainers, mỗi failure mode một kịch bản BDD (thành công, gửi lại, đồng thời, sai chữ ký, sai số tiền, tới muộn).
- API tạo URL và truy vấn giả lập bằng WireMock.
- Sandbox thật chỉ cho smoke test thủ công hoặc nightly qua tunnel.
Từ vựng tiếng Anh
| Term | Phát âm | Nghĩa | Ví dụ câu tiếng Anh dùng trong phỏng vấn |
|---|---|---|---|
| late notification | /leɪt ˌnoʊ.t̬ə.fəˈkeɪ.ʃən/ | thông báo tới muộn | “A late notification still records the payment, then triggers a refund if needed.” |
| reconciliation | /ˌrek.ənˌsɪl.iˈeɪ.ʃən/ | đối soát | “Daily reconciliation compares the gateway statement with our payments.” |
| settlement | /ˈset̬.əl.mənt/ | quyết toán, tiền về | “Settlement arrives the next day minus the gateway fee.” |
| refund | /ˈriː.fʌnd/ | hoàn tiền | “Refunds go through an outbox with an idempotency key.” |
| sandbox | /ˈsænd.bɑːks/ | môi trường thử | “We use the sandbox for smoke tests, not for CI.” |
| failure mode | /ˈfeɪl.jər moʊd/ | kiểu hỏng | “I list every failure mode and how the design handles it.” |
| statement | /ˈsteɪt.mənt/ | sao kê | “We load the gateway statement into a staging table every morning.” |
| clearing account | /ˈklɪr.ɪŋ əˈkaʊnt/ | tài khoản trung gian | “The clearing account should drop back after each settlement.” |
| rate limit | /reɪt ˈlɪm.ɪt/ | giới hạn tần suất | “The query job has its own rate limiter to stay under the gateway’s limit.” |
| smoke test | /smoʊk test/ | kiểm thử khói, chạy thử nhanh | “We run a manual smoke test against the sandbox before each release.” |
Ghi chép dựa trên khoá Advanced Backend (Ronin Engineer), viết lại theo cách hiểu của mình.