Skip to content

Platform architecture

Detailed build prompt

A professional implementation prompt and system blueprint for the payment gateway platform.

REST API Signed webhooks Hosted checkout
01Sandbox firstTest outcomes before live onboarding
02Secure eventsHMAC signatures and replay protection
03Clear operationsTransactions, reports, and settlement visibility
04Regional routingProvider-ready payment orchestration

Architecture modules

8 modules
  • Merchant onboarding and KYC
  • API key and webhook management
  • Hosted checkout and payment intent API
  • Provider adapters and smart routing
  • Risk scoring, limits, and manual review
  • Ledger, settlement, and reconciliation
  • Operations controls and audit logging
  • Monitoring, alerts, and support workflows

Core data model

Entities
  • Merchant
  • User
  • ApiCredential
  • PaymentIntent
  • PaymentAttempt
  • Refund
  • WebhookEndpoint
  • SettlementBatch
  • ProviderAccount
  • AuditLog

Delivery phases

Roadmap
  • Phase 1: portal, operations console, sandbox, API docs, and mock payment flow.
  • Phase 2: database-backed merchant onboarding, auth, roles, and audit logs.
  • Phase 3: live provider integration, webhook signing, settlement reports, and reconciliation.
  • Phase 4: risk engine, rate limits, dispute management, observability, and compliance evidence.

Detailed build prompt

Build a professional multilingual payment gateway platform called "WQN Gateway" on Symfony.

Primary objective:
Create a service that lets merchants, platforms, and partners connect to payment acceptance through a secure gateway. The product must include a customer portal, protected operations console, developer API documentation, sandbox simulator, and a clear path to live provider integration.

Languages:
Support English, Lao, Japanese, Korean, Chinese, and Thai. English must be the default locale. Provide a persistent language switcher and keep route structure clean, for example /, /lo, /ja, /ko, /zh, /th and localized portal/docs/sandbox pages.

Main roles:
1. Merchant owner: manages business profile, API keys, checkout settings, webhook endpoints, transactions, refunds, settlements, reports, and support tickets.
2. Merchant developer: views API docs, sandbox keys, request logs, webhook delivery logs, SDK examples, and integration checklist.
3. Finance user: views balances, settlement batches, fees, exports, reconciliation files, and payout bank status.
4. Support operator: reviews tickets, transaction timelines, merchant issues, webhook failures, and provider incidents.
5. Risk/compliance operator: reviews onboarding, KYC/KYB files, risk rules, transaction holds, AML notes, disputes, and audit logs.
6. System operator: manages providers, routing rules, fee plans, currencies, users, roles, system health, and compliance evidence.

Customer portal requirements:
- Dashboard with payment volume, success rate, available balance, pending settlement, dispute count, and webhook health.
- Merchant onboarding with business details, legal entity, beneficial owner data, bank account, website review, documents, and status timeline.
- API credentials with publishable key, secret key, key rotation, IP allowlist, environment selector, and scoped permissions.
- Hosted checkout settings including brand name, logo, return URL, cancel URL, payment methods, currencies, receipt email, and localization.
- Payment links and invoices with amount, currency, description, expiry, customer reference, status, and share URL.
- Transactions table with search, filters, status, method, provider reference, customer reference, timeline, metadata, and export.
- Refunds and disputes workflow with partial refund support, reason codes, evidence upload, and audit trail.
- Webhook management with endpoint URL, event selection, signing secret, retries, recent deliveries, response code, and replay button.
- Settlements with batches, fees, net amount, payout date, bank account, downloadable CSV, and reconciliation status.
- Developer center with quickstart, API reference, request examples, SDK plan, sandbox test scenarios, and integration checklist.

Protected operations console requirements:
- Operations dashboard with live transaction volume, provider health, approval queue, high-risk payments, failed webhooks, and settlement status.
- Merchant approval queue with KYC/KYB review, website review, risk tier, fee plan, supported currencies, and go-live approval.
- Provider management with connector status, credentials vault references, routing weights, failover status, supported methods, and incident notes.
- Risk engine with velocity limits, country rules, amount thresholds, manual review rules, blacklist/allowlist, and scoring logs.
- Transaction monitoring with payment attempts, provider responses, fraud signals, customer metadata, and protected actions.
- Settlement operations with provider reconciliation, merchant payout batches, fee calculation, hold/release actions, and export files.
- Dispute and refund operations with evidence collection, deadlines, status, notes, and financial impact.
- Audit logs for every protected action, API key change, provider setting, settlement release, and merchant approval.
- Compliance center with PCI DSS v4.0.1 evidence checklist, vulnerability scan records, access reviews, incident response tasks, and data retention controls.

Payment API requirements:
- Authentication using Bearer secret keys for server-side API calls. Never expose secret keys in browsers.
- Use idempotency keys for all mutating payment, refund, and checkout session requests.
- Endpoints: create payment intent, retrieve payment, capture payment, cancel payment, create refund, create checkout session, list transactions, list settlements, create webhook endpoint, replay webhook.
- Webhooks must be signed with HMAC SHA-256 over timestamp and raw payload. Include replay protection and timestamp tolerance.
- Standard payment states: requires_payment_method, requires_action, processing, requires_review, succeeded, failed, canceled, refunded, partially_refunded, disputed.
- Store only tokens and provider references. Do not store raw card numbers, CVV, magnetic stripe data, PIN data, or sensitive authentication data.
- Prefer hosted checkout or provider-side tokenization to reduce PCI scope.
- Include rate limits, request IDs, structured errors, pagination, metadata fields, and versioned API paths.

Security and compliance requirements:
- Design around PCI DSS v4.0.1. Treat payment account data as sensitive and minimize scope.
- Follow OWASP API Security Top 10 guidance, especially object-level authorization, authentication, property-level authorization, rate limiting, and safe consumption of third-party APIs.
- Enforce HTTPS, secure cookies, CSRF protection for browser forms, RBAC, MFA-ready operator accounts, audit logs, encrypted secrets, and least-privilege provider credentials.
- Add monitoring for webhook failures, provider errors, abnormal decline spikes, suspicious velocity, settlement mismatches, and privileged access changes.
- Provide a clear note that going live requires payment provider contracts, legal review, PCI validation path, data processing terms, and local regulatory review.

UI/UX requirements:
- Build a quiet professional operations interface, not a marketing landing page.
- First screen should feel like a usable gateway console with metrics, transaction monitor, provider routing, and clear navigation.
- Customer and protected operations areas must be visually distinct but consistent.
- Use dense, scannable layouts, tables, status badges, segmented controls, compact forms, and dashboard panels.
- Keep cards to 8px radius or less. Avoid decorative gradient blobs and oversized hero-only pages.
- Ensure mobile responsiveness, readable tables, stable dimensions, and no text overlap.

Implementation phases:
Phase 1: static professional MVP with multilingual pages, customer portal, docs, sandbox, prompt, mock payment simulation, and production deployment.
Phase 2: database entities, authentication, roles, merchant onboarding, API key storage, webhook endpoint storage, and audit logs.
Phase 3: real provider adapter integration, hosted checkout handoff, webhook signing, settlement batch generation, and reconciliation.
Phase 4: risk engine, dispute management, observability dashboards, compliance evidence workflows, automated tests, and hardening.

Acceptance criteria:
- The site loads at https://gateway.wqnwqn.com with English as default.
- Language switcher works for English, Lao, Japanese, Korean, Chinese, and Thai.
- Customer portal, protected operations console, API docs, sandbox simulator, and prompt/spec page are available.
- Sandbox form returns a mock payment ID, request ID, status, webhook event, and signature.
- No sensitive source files are exposed from the web root.
- Composer validation and Symfony production cache warmup pass.

Build with confidence

Explore the API, simulate payment outcomes, and prepare a clear production-readiness checklist.
Start in Sandbox Talk to support