Summary of "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:
- Customer scans QR with bank app.
- Bank validates QR via payment provider (e.g., VNPay).
- Transaction routed through national switch (NAPAS 24/7 in Vietnam).
- Funds settle to merchant (often into virtual/sub-accounts).
- Payment gateway receives bank webhook.
- Gateway maps bank webhook to internal transaction ID, updates status.
- 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:
- Payment method(s) — QR is the simplest to start with.
- Merchant integration — APIs, webhooks, onboarding flows.
- 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.
Category
Technology
Share this summary
Is the summary off?
If you think the summary is inaccurate, you can reprocess it with the latest model.
Preparing reprocess...