Thiết kế hệ thống Payment Gateway | Trần Quốc Huy - Wecommit

Overview

A technical walkthrough and practical guide to designing a payment gateway (Fintech) system, with focus on QR-based domestic payments and expansion to credit-card processing. Covers architecture, merchant integration, security, data design, operations, and implementation recommendations.

---

Key components and architecture

• Layers and infrastructure:

  • API gateway (external interface, security, rate-limiting)
  • Load balancer
  • Core microservices (payment processing, webhooks, refunds, notifications)
  • Message queue (MQ) for decoupling and retryable workflows
  • Databases and object storage
  • VPC clusters and network isolation

• Microservice approach:

  • Separate services for payments, webhooks, refunds, notifications, reconciliation, monitoring/auditing

• High-availability guidance:

  • Multi-region / multi-provider deployments
  • Backups, replication, and failover to reduce blast radius
  • Aim for near-5‑9s uptime where appropriate

---

QR-code payment flow (domestic / bank transfers)

Types of QR codes:

• Static QR: store-level, reusable
• Dynamic QR: order-level, generated per transaction

Typical end-to-end flow:

1. Customer scans QR with bank app.
2. Bank validates QR via payment provider (e.g., VNPay).
3. Transaction routed through national switch (NAPAS 24/7 in Vietnam).
4. Funds settle to merchant (often into virtual/sub-accounts).
5. Payment gateway receives bank webhook.
6. Gateway maps bank webhook to internal transaction ID, updates status.
7. Gateway notifies merchant via webhook.

Design recommendations:

• Use a master account + virtual/sub-accounts to map incoming transfers to merchant accounts and to enable tracking.
• Store transaction records and run reconciliation before payouts. Consider delaying payouts 24–48 hours for additional checks.
• Employ worker processes for webhook handling and retry logic.
• Security layers: HTTPS/TLS, API keys, signatures on webhook payloads, IP whitelisting.
• Consider using VTQR / local QR standards for compatibility.

---

Merchant onboarding & integration

Onboarding flow:

• Manual KYC/verification step (admin verifies business info)
• Provision merchant credentials:
  • Merchant ID
  • Access Key / Secret Key
  • Webhook endpoint
  • IP whitelist
  • Test environment access

APIs to expose:

• Create transaction / generate QR
• Check status
• Refund
• Webhooks for asynchronous updates

UX and secrets:

• Return QR data to merchant for display on POS
• Secure storage/display of API secrets (e.g., show_secret_once policy)

---

Webhooks, idempotency, and workers

• Handle bank/payment switch webhooks with dedicated worker processes.
• Use idempotency / event keys (event ID, order ID) to prevent duplicate processing.
• Persist webhook events in a queue or datastore; retry on transient failures.
• Verify webhook authenticity using signatures and optionally IP whitelisting.
• Use dead-letter queues for non-recoverable failures and clear retry policies.

---

Refund handling

• Store refund records in the database and push refund events into MQ.
• Workers attempt refunds until success; update merchant and refund status.
• Typical refund reasons: duplicate payment, merchant-initiated refund, order cancellation.
• Refund fees may apply (especially for card refunds).
• Use tokenized/stored payment info to refund without prompting the user to re-enter account/card details.

---

Credit-card integration (PCI concerns)

Card flow basics:

• Authorization (hold)
• Capture
• Settlement
• Refunds (void vs refund)

Authentication and flows:

• 3DS / OTP often used for authentication during authorization.
• Void cancels a pre-capture authorization (often without fees).
• Refunds after settlement may incur fees and longer processing.

Strategy recommendations:

• Short-term: delegate heavy card processing to certified payment processors (Stripe, PayPal-like partners) to reduce immediate PCI scope and licensing complexity.
• Long-term: obtain required licenses and integrate directly with card networks (Visa/Mastercard) when ready.

---

Security, PCI-DSS, tokenization & key management

• PCI-DSS requirements: firewalling, data protection, access control, logging/audit, key management.
• Never store PAN/CCV in cleartext; use tokenization to replace PAN with tokens for later charges/refunds.
• Prefer client-side tokenization (iframe or SDK) so raw card data never touches merchant servers.
• Use KMS/HSM to generate data keys, encrypt sensitive fields before database storage, rotate keys periodically, and limit decryption scope.
• For databases: consider field-level encryption, truncate/mask displayed values, and audit access.

---

Data design, scaling, and performance

• Database is often the main bottleneck; design for partitioning/sharding by merchant ID and/or time.
• Separate hot (online) data vs historical data:
  • Use End Of Day (EOD) jobs to move daily tables to history/archive to keep live tables small and fast.
• Use message queues to decouple components and enable retryable workflows.
• Partition queues and workloads across workers (e.g., separate queues per processing type).
• Plan for concurrency, locking, and recovery (persist locks/archives to ensure restore after failures).

---

Settlement and reconciliation

• Card settlement is separate from authorization/capture; final fund movement occurs at settlement.
• Reconciliation:
  • Download daily settlement reports (CSV/XML via SFTP) from processors/banks
  • Compare reports with internal DB transactions
  • Update statuses and generate financial reports
• Build automated reconciliation jobs and reporting to reduce manual effort and errors.

---

Operational considerations

• Implement monitoring, alerting, and auditing (transaction tracing, fraud monitoring).
• Plan retries, dead-letter queues, and observability for asynchronous flows.
• Apply rate-limiting, API throttling, and security controls at the API gateway.
• Maintain clear runbooks for incident response, failover, and disaster recovery.

---

Implementation guidance / recommended approach

Three essential pillars to start:

1. Payment method(s) — QR is the simplest to start with.
2. Merchant integration — APIs, webhooks, onboarding flows.
3. Security — authentication, TLS, encryption, reduce PCI scope.

Practical roadmap:

• Integrate with existing certified payment processors for card payments initially.
• Build core capabilities first:
  • Reliable DB schema and transaction records
  • MQ-based processing
  • Idempotency and webhook handling
  • Reconciliation flows
• Expand to additional payment methods (cards, e-wallets) once compliance and licensing are addressed.

---

Practical tutorials / guides (covered or implied)

• End-to-end QR payment: scan → bank → NAPAS → webhook → update → payout
• Merchant onboarding and credentials management
• Generating and managing static vs dynamic QR codes (VTQR standard suggestion)
• Designing webhook workers with idempotency and retry
• Implementing refund flows using MQ and persistent records
• Database partitioning/sharding strategies and EOD archival
• Card payment flow (auth/capture/settlement/refund) and PCI-DSS basics
• Tokenization and KMS-based encryption/decryption lifecycle

---

Common pitfalls and cautions

• Underestimating security and PCI compliance requirements for card processing
• Treating database design as an afterthought — DB often becomes the scalability bottleneck
• Forgetting idempotency and retry logic for webhooks/events
• Performing immediate auto-payouts without reconciliation, which increases fraud and operational risk

---

Main speakers / sources

• Trần Quốc Huy (Huy Tran Quoc Huy) — presenter, database & system optimization expert, founder of WCOM 100X community
• Trung — backend technical lead/engineer (≈10 years experience)
• Dinh — backend developer specializing in Node.js and cloud, e‑commerce/logistics domain

Note: references in the talk include VNPay, NAPAS 24/7, banks like Vietcombank/BIDV, and international processors like Stripe/PayPal as examples.