Tránh trừ tiền hai lần: Idempotency trong API thanh toán

Tránh trừ tiền hai lần: Idempotency trong API thanh toánPrevent Double Charge: API Idempotency for Payments

Cách thiết kế API thanh toán idempotent để tránh lỗi trừ tiền hai lần, với ví dụ thực tế trong Spring Boot 3 và Go.How to design idempotent payment APIs to prevent double‑charge bugs, with practical Java Spring Boot 3 and Go examples.

2 tháng 11, 2026November 2, 20266 phút đọc6 min read200

Bạn có bao giờ gặp trường hợp khách hàng phàn nàn rằng họ bị trừ tiền hai lần sau khi nhấn nút "Thanh toán"? Thường thì lỗi này xuất phát từ idempotency không được thực thi đúng cách: khi một request bị retry (do timeout, network glitch, hoặc client nhấn lại) server lại thực hiện lại toàn bộ transaction.

Nguyên nhân phổ biến#

Retry tự động của client – HTTP client (Postman, Retrofit, hoặc browser) sẽ tự gửi lại request nếu không nhận được response trong thời gian quy định.
Timeout ở gateway – API gateway (nghĩa là Nginx, Kong, hoặc AWS API GW) có thể trả về 504 và client sẽ retry.
Crash giữa‑chừng – Khi service bị restart ngay sau khi ghi vào DB nhưng chưa commit, transaction có thể bị thực thi lại.

Nếu không có cơ chế idempotent key, mỗi lần request được thực hiện lại, hệ thống sẽ tạo một bản ghi giao dịch mới, dẫn tới double‑charge.

Nguyên tắc idempotency#

Idempotency‑Key: một giá trị duy nhất do client cung cấp (UUID, order‑id, hoặc hash của payload). Server phải lưu trữ key này và kết quả tương ứng.
Idempotent operation: nếu key đã tồn tại, trả về cùng một response (status 200/201) và không thực hiện lại logic thay đổi trạng thái.
Persist key: key phải được ghi vào DB trong cùng transaction với nghiệp vụ chính để tránh mất đồng bộ khi crash.

Tránh trừ tiền hai lần: Idempotency trong API thanh toánPrevent Double Charge: API Idempotency for Payments

2 tháng 11, 2026November 2, 20266 phút đọc6 min read200

Nguyên nhân phổ biến#

Retry tự động của client – HTTP client (Postman, Retrofit, hoặc browser) sẽ tự gửi lại request nếu không nhận được response trong thời gian quy định.
Timeout ở gateway – API gateway (nghĩa là Nginx, Kong, hoặc AWS API GW) có thể trả về 504 và client sẽ retry.
Crash giữa‑chừng – Khi service bị restart ngay sau khi ghi vào DB nhưng chưa commit, transaction có thể bị thực thi lại.

Nếu không có cơ chế idempotent key, mỗi lần request được thực hiện lại, hệ thống sẽ tạo một bản ghi giao dịch mới, dẫn tới double‑charge.

Nguyên tắc idempotency#

Idempotency‑Key: một giá trị duy nhất do client cung cấp (UUID, order‑id, hoặc hash của payload). Server phải lưu trữ key này và kết quả tương ứng.
Idempotent operation: nếu key đã tồn tại, trả về cùng một response (status 200/201) và không thực hiện lại logic thay đổi trạng thái.
Persist key: key phải được ghi vào DB trong cùng transaction với nghiệp vụ chính để tránh mất đồng bộ khi crash.

package handler import ( "context" "encoding/json" "net/http" "time" "github.com/google/uuid" "github.com/jackc/pgx/v5" ) type PaymentRequest struct { UserID string `json:"user_id"` Amount float64 `json:"amount"` Currency string `json:"currency"` } type PaymentResponse struct { TransactionID string `json:"transaction_id"` Status string `json:"status"` Amount float64 `json:"amount"` } // IdempotencyEntry lưu key và response đã trả về type IdempotencyEntry struct { Key string `json:"key"` Response PaymentResponse `json:"response"` Expired time.Time `json:"expired"` } func PayHandler(db *pgx.Conn) http.HandlerFunc { return func(w http.ResponseWriter, r *http.Request) { ctx := r.Context() key := r.Header.Get("Idempotency-Key") if key == "" { http.Error(w, "Missing Idempotency-Key", http.StatusBadRequest) return } // 1️⃣ Kiểm tra key trong DB var stored PaymentResponse err := db.QueryRow(ctx, "SELECT response FROM idempotency WHERE key=$1", key).Scan(&stored) if err == nil { // Key đã tồn tại → trả về kết quả cũ json.NewEncoder(w).Encode(stored) return } if err != pgx.ErrNoRows && err != nil { http.Error(w, "Internal Server Error", http.StatusInternalServerError) return } // 2️⃣ Đọc payload var req PaymentRequest if err := json.NewDecoder(r.Body).Decode(&req); err != nil { http.Error(w, "Invalid JSON", http.StatusBadRequest) return } // 3️⃣ Thực hiện payment trong một transaction tx, err := db.BeginTx(ctx, pgx.TxOptions{}) if err != nil { http.Error(w, "DB error", http.StatusInternalServerError) return } defer tx.Rollback(ctx) // giả sử hàm charge() gọi tới PSP và trả về transactionID txnID := uuid.NewString() // Lưu giao dịch _, err = tx.Exec(ctx, "INSERT INTO payments (id, user_id, amount, currency) VALUES ($1,$2,$3,$4)", txnID, req.UserID, req.Amount, req.Currency) if err != nil { http.Error(w, "DB error", http.StatusInternalServerError) return } // Tạo response resp := PaymentResponse{TransactionID: txnID, Status: "SUCCESS", Amount: req.Amount} // Lưu idempotency key và response trong cùng transaction _, err = tx.Exec(ctx, "INSERT INTO idempotency (key, response, expired) VALUES ($1,$2,$3)", key, resp, time.Now().Add(72*time.Hour)) if err != nil { http.Error(w, "DB error", http.StatusInternalServerError) return } // Commit transaction if err = tx.Commit(ctx); err != nil { http.Error(w, "Commit failed", http.StatusInternalServerError) return } w.WriteHeader(http.StatusCreated) json.NewEncoder(w).Encode(resp) } }

@RestController @RequestMapping("/api/payments") public class PaymentController { private final PaymentService paymentService; private final IdempotencyRepository idempotencyRepo; public PaymentController(PaymentService paymentService, IdempotencyRepository idempotencyRepo) { this.paymentService = paymentService; this.idempotencyRepo = idempotencyRepo; } @PostMapping public ResponseEntity<PaymentResponse> pay( @RequestHeader("Idempotency-Key") String key, @RequestBody @Valid PaymentRequest request) { // 1️⃣ Check if the key already exists var existing = idempotencyRepo.findByKey(key); if (existing.isPresent()) { return ResponseEntity.ok(existing.get().getResponse()); // return previous result } // 2️⃣ Execute the business logic and store the key in the same transaction var response = paymentService.process(request); var entry = new IdempotencyEntry(key, response); idempotencyRepo.save(entry); return ResponseEntity.status(HttpStatus.CREATED).body(response); } }

package handler import ( "context" "encoding/json" "net/http" "time" "github.com/google/uuid" "github.com/jackc/pgx/v5" ) type PaymentRequest struct { UserID string `json:"user_id"` Amount float64 `json:"amount"` Currency string `json:"currency"` } type PaymentResponse struct { TransactionID string `json:"transaction_id"` Status string `json:"status"` Amount float64 `json:"amount"` } // IdempotencyEntry stores the key and the previously returned response type IdempotencyEntry struct { Key string `json:"key"` Response PaymentResponse `json:"response"` Expired time.Time `json:"expired"` } func PayHandler(db *pgx.Conn) http.HandlerFunc { return func(w http.ResponseWriter, r *http.Request) { ctx := r.Context() key := r.Header.Get("Idempotency-Key") if key == "" { http.Error(w, "Missing Idempotency-Key", http.StatusBadRequest) return } // 1️⃣ Look up the key first var stored PaymentResponse err := db.QueryRow(ctx, "SELECT response FROM idempotency WHERE key=$1", key).Scan(&stored) if err == nil { // Key exists → return the stored response json.NewEncoder(w).Encode(stored) return } if err != pgx.ErrNoRows && err != nil { http.Error(w, "Internal Server Error", http.StatusInternalServerError) return } // 2️⃣ Decode payload var req PaymentRequest if err := json.NewDecoder(r.Body).Decode(&req); err != nil { http.Error(w, "Invalid JSON", http.StatusBadRequest) return } // 3️⃣ Run the payment inside a DB transaction tx, err := db.BeginTx(ctx, pgx.TxOptions{}) if err != nil { http.Error(w, "DB error", http.StatusInternalServerError) return } defer tx.Rollback(ctx) // Simulated charge – in reality you would call a PSP here txnID := uuid.NewString() _, err = tx.Exec(ctx, "INSERT INTO payments (id, user_id, amount, currency) VALUES ($1,$2,$3,$4)", txnID, req.UserID, req.Amount, req.Currency) if err != nil { http.Error(w, "DB error", http.StatusInternalServerError) return } resp := PaymentResponse{TransactionID: txnID, Status: "SUCCESS", Amount: req.Amount} // Store the idempotency key and response in the same transaction _, err = tx.Exec(ctx, "INSERT INTO idempotency (key, response, expired) VALUES ($1,$2,$3)", key, resp, time.Now().Add(72*time.Hour)) if err != nil { http.Error(w, "DB error", http.StatusInternalServerError) return } // Commit everything atomically if err = tx.Commit(ctx); err != nil { http.Error(w, "Commit failed", http.StatusInternalServerError) return } w.WriteHeader(http.StatusCreated) json.NewEncoder(w).Encode(resp) } }

Key takeaways#

Enforce Idempotency-Key from the client and store it in a durable table.

Execute the payment and the key insertion in the same transaction.

Set an appropriate TTL for stored keys and always return the original response on repeats.

Validate the implementation with unit and chaos tests to guarantee no double‑charge can slip through.

Apply the five‑point rule of thumb to every microservice that performs money movements.

Have you ever dealt with a double‑charge incident? Share your story and the fix you applied in the comments!

Tránh trừ tiền hai lần: Idempotency trong API thanh toánPrevent Double Charge: API Idempotency for Payments

Nguyên nhân phổ biến#

Nguyên tắc idempotency#

Tránh trừ tiền hai lần: Idempotency trong API thanh toánPrevent Double Charge: API Idempotency for Payments

Nguyên nhân phổ biến#

Nguyên tắc idempotency#

Một vài lưu ý thực tiễn#

Triển khai trong Go (Go 1.22)#

Kiểm thử nhanh#

Quy tắc vàng (Rule of thumb)#

Tóm tắt#

Common causes#

Idempotency principles#

Spring Boot 3 (Java 21) implementation#

Practical tips#

Go (Go 1.22) implementation#

Quick testing checklist#

Rule of thumb#

Key takeaways#

Thảo luậnDiscussion

Nguyên nhân phổ biến#

Nguyên tắc idempotency#

Nguyên nhân phổ biến#

Nguyên tắc idempotency#

Một vài lưu ý thực tiễn#

Triển khai trong Go (Go 1.22)#

Kiểm thử nhanh#

Quy tắc vàng (Rule of thumb)#

Tóm tắt#

Common causes#

Idempotency principles#

Spring Boot 3 (Java 21) implementation#

Practical tips#

Go (Go 1.22) implementation#

Quick testing checklist#

Rule of thumb#

Key takeaways#

Bài học liên quanRelated lessons

Retry with Exponential Backoff

Thảo luậnDiscussion