Platform architecture & tech stack
Architecture vision
Our approach
We designed a financial-grade payment platform built on:
- API-first architecture — REST APIs, OpenAPI/Swagger, developer docs
- Multi-tenant infrastructure — Reseller → Merchant hierarchy and isolation
- Cloud-native & containerized — AWS: container images in Amazon ECR, API workloads on Amazon EKS (Kubernetes); Docker build and CI/CD push to ECR and deploy to the cluster (see this repo’s
azure-pipelines.yml/ci/azure-pipelines.stages.yml; additional infra may live inVi.Cloud.Infrastructurewhere your team still references it) - Event-driven processing — State only what is live (async flows, webhooks, queues); avoid implying NATS unless those are deployed and named
- Security-first design — OAuth2/OIDC (Keycloak), HMAC for POS, TLS; PCI-aligned wording unless you hold specific certifications
Multi-tenant model
Platform coverage
Full payment ecosystem
- POS device application (Android-based)
- Embedded SDK payments
- Checkout web (hosted & embedded)
- Payment links
- Subscription billing
- API-based integrations
One platform, multiple revenue channels — tag each capability internally as Live / Beta / Roadmap before external claims.
High-level architecture
Core components
| Block | Description |
|---|---|
| Payment API | Unified transaction entry point; POS, gateway-backed flows, API integrations |
| Payout engine | Money disbursement after settlement: pays merchants, resellers, or partners via ACH (batch and same-day where supported), RTP (The Clearing House real-time payments, where your bank/processor participates), and FedNow (Federal Reserve instant payments, where available). Where your product and compliance program allow, payouts may also use USDT (Tether) or other stablecoin rails on supported networks. Each rail has its own cutoffs, limits, eligibility, and reconciliation—tag internally as Live / Beta / Roadmap so external claims match what you actually ship. |
| Checkout system | Hosted checkout, payment links, embedded UI — align with product stage |
| Subscription engine | Recurring billing, retries, dunning — align with product stage |
| POS device application | Android app; secure channel; offline + sync — as shipped |
| POS ↔ API | HMAC-authenticated requests |
| KYB — Know Your Business | KYB is due diligence on the business as a legal entity: legal name, entity type, tax or registration identifiers, industry, physical address, website, and payout banking. It answers “who is the company we are boarding and paying?” On the platform, that data is collected through progressive onboarding APIs (structured JSON per step) so risk and compliance teams can review the entity before go-live. What satisfies KYB in your program (thresholds, document collection, manual review) remains your policy. |
| KYC — Know Your Customer | KYC is due diligence on natural persons: owners, officers, or others who control or materially benefit from the account. It typically covers identity verification (government ID, liveness where required), address and date of birth, and AML screening (sanctions / PEP lists). The backoffice stores onboarding contact fields where applicable and uses Plaid for stronger checks: Link (token + UI flow), public token exchange, verification status, Plaid Identity Verification (create, get, list, retry), and webhooks for async updates. Plaid routes use Bearer + session like the rest of the API; the Plaid webhook endpoint is unauthenticated by design—verify Plaid’s webhook signature before trusting payloads in production. |
| Merchant & reseller onboarding | Merchants: POST /merchant/create, 7 steps (current_step 1–7)—business and KYB fields, contact (KYC-oriented signals), address, product/pricing, banking, agreements, then review/submit (e.g. draft → pending); reseller context applies; merchant portal access can be tied to Keycloak for the contact email. Resellers: POST /reseller/create, 9 steps (1–9)—business, contact, address, fees, banking, domain, branding, agreements, optional metadata. Both flows require an authenticated session. See Swagger for request schemas. |
Security architecture
- mTLS via Istio — confirm mesh policy before claiming everywhere
- OAuth 2.0 / OIDC (Keycloak) for users and machine clients
- HMAC for POS
- Tokenized payment data — typically via processor/gateway
- TLS end-to-end for clients
- PCI-DSS aligned — use “aligned” unless formally certified
Infrastructure stack
| Area | Technologies |
|---|---|
| Cloud (AWS) | Amazon EKS for Kubernetes; Amazon ECR for private container images; pipeline-authenticated push (aws ecr …, docker push) and cluster deploy (kubectl / kubeconfig for EKS). PostgreSQL, Redis, and Keycloak often run as managed or in-cluster services—name what you actually use (e.g. RDS, ElastiCache, self-managed). |
| Orchestration | Kubernetes (EKS), Rancher |
| Networking | Istio service mesh |
| Ingress | Istio Gateway, VirtualServices, host-based routing |
| Benefits | Traffic management, observability, mTLS where enabled |
Backend & data (codebase-aligned)
The Vi.Backoffice.Api service is Go (Gin), not Java Spring Boot.
| Layer | Stack |
|---|---|
| Backend | Go, Gin, controllers / services / models |
| API docs | Swag → OpenAPI, Swagger UI |
| Auth | Keycloak, JWT; M2M via POST /client/session (legacy /auth/token) |
| Data | PostgreSQL, GORM, multi-tenant modeling |
| Cache | Redis |
| Observability | OpenTelemetry / Jaeger, /health/* |
| Integrations | Gateway adapters, Plaid (KYC/AML & Identity Verification), gRPC rule engine |
Processing architecture
- Payment engine — transaction lifecycle
- Payout engine — disbursement (ACH, RTP, FedNow, optional USDT / stablecoin)—see Core components; settlement & splits — stage accurately
- Risk engine — rules / fraud — tie to real integration
Why it matters: async resilience, queue-based durability with idempotent operations for financial safety.
MCP (Model Context Protocol)
MCP is an open standard for connecting AI assistants and IDE tooling (for example Cursor or other MCP-capable clients) to MCP servers that expose tools, resources, and context in a structured way. It is not the merchant or reseller control panel; portal features, API clients, webhooks, and permissions live in the backoffice API and related apps.
Where you deploy MCP servers (e.g. to query docs, run safe operational helpers, or integrate internal runbooks), they sit beside the core platform as an optional developer-experience layer—the dashed edge in the diagram above indicates that relationship rather than a payment-path dependency.
Multi-channel payments
Same core backend; channels include POS, SDK, checkout web, payment links, subscriptions — clarify maturity per channel.
Scalability & reliability
- Stateless API tier → horizontal scale on Kubernetes (EKS); cluster / node / pod autoscaling where enabled
- Istio traffic management and isolation
- High throughput — back with metrics when pitching