Payment SystemPayment System

giao dịch mỗi ngàypayments a day

300k

giao dịch mỗi ngàypayments a day

lúc flash saleduring a flash sale

~150/s

lúc flash saleduring a flash sale

tạo link thanh toánto create a payment link

< 2s

tạo link thanh toánto create a payment link

chênh lệch sau đối soátunexplained difference after reconciliation

0 đ

chênh lệch sau đối soátunexplained difference after reconciliation

Payment Service tạo payment intent, gọi cổng qua adapter và chờ webhook. Webhook được xác minh chữ ký, khử trùng rồi cập nhật trạng thái cùng outbox trong một transaction. Job đối soát hỏi lại cổng cho các giao dịch PENDING quá lâu. Chọn kịch bản “Mất webhook” hoặc “Webhook trùng” để xem cách hệ thống tự sửa.The Payment Service creates a payment intent, calls the gateway through an adapter and waits for a webhook. The webhook is signature-checked, deduplicated, and updates the status together with an outbox row in one transaction. A reconciliation job asks the gateway again about payments stuck in PENDING. Pick “Webhook lost” or “Duplicate webhook” to see how the system corrects itself.

1. 1

   Trừ tiền hai lần khi khách bấm lạiCharging twice when the customer clicks again

   Client gửi Idempotency-Key cố định cho mỗi lần thanh toán đơn. Bảng payment có unique(idempotency_key); request lặp trả lại payment cũ thay vì tạo giao dịch mới ở cổng. Khi cổng hỗ trợ (Stripe), truyền luôn key sang cổng.The client sends a fixed Idempotency-Key per checkout. The payment table has unique(idempotency_key); a repeated request returns the existing payment instead of creating a new charge. When the gateway supports it (Stripe), pass the key through as well.
2. 2

   Mỗi cổng một kiểu APIEvery gateway speaks its own API

   Interface PaymentGateway chung (createIntent, verifySignature, parse, queryStatus, refund). VNPay, MoMo, Stripe là các adapter; Strategy chọn adapter theo provider của payment.One PaymentGateway interface (createIntent, verifySignature, parse, queryStatus, refund). VNPay, MoMo and Stripe are adapters; a Strategy picks the adapter from the payment's provider.

   AdapterStrategy
3. 3

   Webhook giả, trùng hoặc sai thứ tựForged, duplicate or out-of-order webhooks

   Xác minh HMAC trên raw body trước khi parse. Lưu (provider, event_id) đã xử lý để bỏ qua bản trùng. State machine chỉ cho chuyển hợp lệ, nên FAILED tới sau SUCCEEDED bị bỏ qua.Verify the HMAC over the raw body before parsing. Store processed (provider, event_id) pairs to drop duplicates. The state machine only allows valid transitions, so a FAILED arriving after SUCCEEDED is ignored.

   State
4. 4

   Webhook không bao giờ tớiThe webhook never arrives

   Job polling hỏi queryStatus cho payment PENDING quá 15 phút, giãn cách tăng dần. Đối soát cuối ngày so từng dòng với báo cáo quyết toán của cổng.A polling job calls queryStatus for payments PENDING over 15 minutes, with growing intervals. The nightly reconciliation matches every row against the gateway settlement report.

   Retry with Exponential Backoff
5. 5

   Đã nhận tiền nhưng đơn không cập nhậtMoney taken but the order never updates

   Ghi trạng thái payment và outbox payment.succeeded trong cùng transaction; relay đẩy sang Kafka sau commit. Order và Inventory chạy như một saga: thất bại thì nhả hàng đang giữ, hoặc hoàn tiền nếu không còn hàng.Write the payment status and a payment.succeeded outbox row in one transaction; a relay publishes after commit. Order and Inventory run as a saga: on failure release the reservation, or refund when stock is gone.

   Transactional OutboxSaga
6. 6

   Hoàn tiền một phần và sai số tiềnPartial refunds and rounding errors

   Tiền lưu bằng số nguyên đơn vị nhỏ nhất (VND không có xu, USD tính cent) hoặc BigDecimal, không dùng double. Tổng các refund SUCCEEDED không vượt số đã thu; kiểm tra dưới khoá dòng payment.Store money as integer minor units (VND has no subunit, USD uses cents) or BigDecimal, never double. The sum of SUCCEEDED refunds cannot exceed the captured amount; check it under a lock on the payment row.

   Specification
7. 7

   Cổng chậm làm nghẽn checkoutA slow gateway clogs checkout

   Timeout ngắn khi gọi cổng, circuit breaker theo từng cổng. Breaker mở thì ẩn phương thức đó trên trang thanh toán thay vì để khách chờ.Short timeouts on gateway calls and a circuit breaker per gateway. When a breaker opens, hide that method on the checkout page instead of making customers wait.

   Circuit Breaker

Java: endpoint webhook xác minh chữ ký, khử trùng, đi qua state machine rồi ghi outbox. Go: job đối soát hỏi lại cổng cho các payment PENDING quá lâu và sửa trạng thái bằng UPDATE có điều kiện.Java: a webhook endpoint that verifies the signature, deduplicates, goes through the state machine and writes the outbox. Go: a reconciliation job that asks the gateway about stale PENDING payments and fixes them with a conditional UPDATE.

@RestController
@RequiredArgsConstructor
public class WebhookController {
    private final Map<String, PaymentGateway> gateways; // "vnpay", "momo", "stripe"1
    private final PaymentRepository payments;
    private final ProcessedEventRepository processed;
    private final OutboxRepository outbox;

    @PostMapping("/webhooks/{provider}")
    @Transactional
    public ResponseEntity<Void> handle(@PathVariable String provider,
                                       @RequestHeader HttpHeaders headers,
                                       @RequestBody String rawBody) {
        PaymentGateway gw = gateways.get(provider);
        if (gw == null || !gw.verifySignature(headers, rawBody)) {2
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
        }
        GatewayEvent ev = gw.parse(rawBody);
        if (!processed.insertIfAbsent(provider, ev.eventId())) {3
            return ResponseEntity.ok().build();          // duplicate delivery
        }
        Payment p = payments.lockByGatewayRef(provider, ev.reference()); // FOR UPDATE
        if (p.amountMinor() != ev.amountMinor()) {
            p.flagForReview(ev);                         // never auto-succeed
            return ResponseEntity.ok().build();
        }
        if (!p.canMoveTo(ev.status())) {4
            return ResponseEntity.ok().build();          // stale or out of order
        }
        p.moveTo(ev.status(), "webhook");                // PENDING -> SUCCEEDED
        if (p.status() == PaymentStatus.SUCCEEDED) {
            outbox.save(OutboxEvent.of("payment.succeeded", p.orderId(), p));
        }
        return ResponseEntity.ok().build();
    }
}

type Reconciler struct {
	db       *sql.DB
	gateways map[string]Gateway // "vnpay", "momo", "stripe"
	payments PaymentStore
	outbox   Outbox
}

// Run sweeps PENDING payments older than the cutoff. It runs every 5 minutes
// as the polling fallback; the nightly report job reuses apply().
func (r *Reconciler) Run(ctx context.Context, olderThan time.Duration) error {
	stale, err := r.payments.FindPending(ctx, time.Now().Add(-olderThan))
	if err != nil {
		return err
	}
	for _, p := range stale {
		remote, err := r.gateways[p.Provider].QueryStatus(ctx, p.GatewayRef)1
		if err != nil {
			slog.Warn("query failed, next run retries", "id", p.ID, "err", err)
			continue
		}
		if remote.AmountMinor != p.AmountMinor || remote.Currency != p.Currency {2
			r.payments.FlagMismatch(ctx, p.ID, remote) // a person decides
			continue
		}
		if err := r.apply(ctx, p, remote.Status); err != nil {
			return err
		}
	}
	return nil
}

func (r *Reconciler) apply(ctx context.Context, p Payment, s Status) error {
	tx, err := r.db.BeginTx(ctx, nil)
	if err != nil {
		return err
	}
	defer tx.Rollback()
	res, err := tx.ExecContext(ctx,
		`UPDATE payment SET status = $1, updated_at = now()
		 WHERE id = $2 AND status = 'PENDING'`, s, p.ID)3
	if err != nil {
		return err
	}
	if n, _ := res.RowsAffected(); n == 0 {
		return nil // the webhook got there first
	}
	if s == StatusSucceeded {
		if err := r.outbox.Add(ctx, tx, "payment.succeeded", p.OrderID); err != nil {4
			return err
		}
	}
	return tx.Commit()
}

Mỗi pattern mở bài học tương ứng trong menu Pattern.Each one opens its lesson in the Patterns menu.