Welcome to Payment Gateway

A complete payment processing platform built for scale, security, and learning Payment Gateway is a production-ready microservices ecosystem that handles the full payment lifecycle—from card tokenization to settlement. Built with Go, PostgreSQL, Redis, and Kubernetes, it demonstrates real-world distributed systems architecture while serving as a powerful learning resource.

Live Web Server

https://paymentgateway.redahaloubi.com

What is Payment Gateway?

Payment Gateway is both a functional payment platform and an educational resource showcasing:

Microservices Architecture

7 specialized services communicating via REST and gRPC

PCI-DSS Compliance

Card tokenization, AES-256 encryption, and secure key management

Financial Operations

Multi-currency processing, settlements, and chargeback management

Production Practices

Rate limiting, idempotency, audit logging, and monitoring

Key Features

Payment Operations

Authorization & Capture

Authorize: Hold funds without charging (7-day expiry)
Capture: Charge previously authorized funds (full or partial)
Void: Cancel authorization before capture
Refund: Return funds to customer (full or partial)

Payment Intents

Hosted checkout flow with browser-friendly authentication
Client secret-based security (no API keys in browser)
Automatic expiration after 1 hour
Payment attempt tracking and limits

Multi-Currency Support

Supported: USD, EUR, MAD (Moroccan Dirham)
Automatic currency conversion
Real-time exchange rates
Processing fees calculated per currency

Security & Compliance

Card Tokenization

PCI-compliant token-based system
AES-256-GCM encryption per merchant
Card fingerprinting for duplicate detection
Single-use tokens for sensitive operations

Access Control

Role-based access control (RBAC)
Granular permissions (resource:action format)
Multi-tenant support (different roles per merchant)
API key management with usage tracking

Audit & Compliance

Complete transaction history
Event logging for all state changes
PCI-compliant activity logs
Webhook delivery with retry logic

Developer Experience

Multiple Integration Options

REST APIs for public merchant access
gRPC for high-performance internal communication
Hosted checkout page (no PCI scope for merchants)
CLI tool for quick testing

Developer-Friendly Features

Idempotency support (24-hour cache)
Rate limiting per merchant
Comprehensive test cards
Webhook notifications with HMAC signatures

System Architecture

High-Level Overview

Payment Gateway consists of 7 core microservices organized into layers based on access level and responsibility.

Service Architecture Layers

External Layer

API Gateway - Single entry point for all requests with CORS, rate limiting, and routing

Public Layer

Auth, Merchant, Payment - REST APIs accessible by merchants with authentication

Internal Layer

Tokenization, Transaction - gRPC-only services with no external access

Service Overview

1. API Gateway (Port 8080)

Entry point for all client requests

Responsibilities

CORS handling and security headers
Request/response logging
Rate limiting per merchant (configurable per endpoint)
Request routing to backend services
Circuit breaking for failing services

Key Features

Per-route rate limits (20 payments/sec, 5 login attempts/min)
Request ID generation for tracing
Health check aggregation
Graceful shutdown with connection draining

2. Auth Service (Port 8001, gRPC: 50051)

Authentication, authorization, and access control

Responsibilities

User registration and login (JWT tokens)
Role-based access control (RBAC)
Permission management (resource:action format)
API key generation and validation
Session management with Redis

Key Features

bcrypt password hashing (cost 10)
Account lockout after 5 failed attempts (30-minute lock)
Multi-tenant role assignments
Redis-cached permissions for fast validation
JWT with 24-hour access tokens, 7-day refresh tokens

3. Merchant Service (Port 8002)

Merchant account and team management

Responsibilities

Merchant onboarding and verification
Business profile management
Team member invitations and role assignment
Payment settings configuration (currencies, webhooks)
Multi-merchant support per user

Key Features

Invitation system with email tokens
Role-based team permissions (Owner, Admin, Manager, Staff)
Webhook configuration per merchant
Payment method and currency preferences

4. Payment API Service (Port 8004)

Public payment processing gateway

Responsibilities

Payment orchestration (authorize, capture, void, refund)
Payment Intents for hosted checkout
Idempotency handling (24-hour cache)
Webhook delivery with retry logic
Transaction status tracking

Key Features

Single-step (sale) and multi-step (auth → capture) payments
Payment attempt tracking with limits
Automatic expiration (1 hour for intents)
Test card support for development
Rate limiting: 20 payments/sec, 10,000/hour per merchant

5. Tokenization Service (Port 50052 - gRPC Only)

PCI-compliant card tokenization

Responsibilities

Card data encryption (AES-256-GCM)
Token generation and validation
Card fingerprinting (SHA-256) for duplicate detection
Encryption key rotation (90 days or 1M operations)
BIN database lookups

Key Features

Per-merchant encryption keys
Single-use tokens for sensitive operations
Luhn validation, expiry checks, CVV validation
Never logs full PAN or CVV
Token lifecycle management (active, expired, revoked, used)

6. Transaction Service (Port 50053 - gRPC Only)

Core payment transaction engine

Responsibilities

Transaction lifecycle management (state machine)
Card simulator for testing (no real card processing)
Multi-currency conversion (USD, EUR, MAD)
Settlement batch processing (daily at midnight, T+2)
Chargeback handling

Key Features

Auto-void expired authorizations (7 days)
Processing fee calculation (2.9% + $0.30 in MAD)
Daily settlement reports
Currency conversion with hourly rate updates
Complete transaction event history

7. Payment Checkout (Port 3000)

Hosted checkout application for customers

Responsibilities

Browser-friendly payment flow
Client secret authentication (no API keys exposed)
Payment Intent confirmation
Redirect to success/cancel URLs
Card input validation

Key Features

Built with Next.js 15 and React 19
Real-time card validation (Luhn, expiry, CVV)
Responsive mobile-first design
Automatic expiration handling
Success animation with redirect

Complete Payment Flow

Here’s how a payment flows through the entire system:

Flow Breakdown

Merchant Creates Payment Intent

Merchant server calls /payment-intents with amount, currency, and redirect URLs. Receives client_secret for browser authentication.

Customer Redirected to Checkout

Merchant redirects customer to hosted checkout page with client_secret in URL.

Customer Enters Card & Confirms

Checkout validates card details client-side (Luhn, expiry, CVV)
Sends card data to Payment API (secured by client_secret)
Payment API calls Tokenization Service to encrypt card
Tokenization returns token (never stores plain card data)

Transaction Processing

Payment API calls Transaction Service with token
Transaction Service simulates card processing
Returns authorization code or decline reason
Payment API updates intent status

Customer Redirected Back

Customer redirected to merchant’s success_url or cancel_url based on result.

Webhook Notification

Payment API asynchronously sends webhook to merchant’s configured URL with payment details.

Technology Stack

Backend Services

Language

Go 1.23+ - High-performance, concurrent

HTTP Framework

Gin - Fast HTTP router with middleware

gRPC

Protocol Buffers - Efficient inter-service communication

ORM

GORM - Type-safe database operations

Data Layer

Database

PostgreSQL 15+ - Separate DB per service

Cache

Redis 7+ - Sessions, rate limiting, idempotency

Security

Authentication

JWT (golang-jwt/jwt) - Token-based auth

Encryption

AES-256-GCM - Card data encryption

Hashing

bcrypt (passwords), SHA-256 (fingerprints)

Secrets

HashiCorp Vault (K8s) - Centralized secret management

Infrastructure

Orchestration

Kubernetes (k3d) - Container orchestration

Ingress

NGINX Ingress Controller - Traffic routing

Monitoring

Prometheus + Grafana - Metrics and dashboards

Cloud

AWS EC2 - Production deployment

Frontend

Framework

Next.js 15 - React 19, App Router

Styling

Tailwind CSS - Utility-first CSS

Database Architecture

Each microservice has its own dedicated PostgreSQL database, following microservices best practices:

PostgreSQL Instance
├── auth_db              (Auth Service)
├── merchant_db          (Merchant Service)
├── payment_api_db       (Payment API Service)
├── tokenization_db      (Tokenization Service)
└── transaction_db       (Transaction Service)

Database Isolation Benefits:

Independent scaling per service
Schema changes don’t cascade
Service failures isolated
Enhanced security (each service has credentials only to its DB)

Redis Usage

Single Redis instance shared across services for:

Session storage (Auth JWT sessions)
Rate limiting (API Gateway)
Caching (Merchant/Payment data)
Idempotency (24-hour request cache)

Security & Compliance

PCI-DSS Compliance

Card Data Protection:

Card numbers never logged or stored in plaintext
Tokenization reduces PCI scope for merchants
AES-256-GCM encryption at rest
TLS 1.3 for data in transit

Encryption Strategy

Per-Merchant Encryption Keys

Each merchant has unique AES-256 keys stored in HashiCorp Vault (production) or encrypted at rest.

Field-Level Encryption

Card number, CVV, and cardholder name encrypted separately with GCM authentication tags.

Automatic Key Rotation

Keys rotated every 90 days or after 1 million encryptions (whichever comes first).

Card Fingerprinting

SHA-256 hash of card_number + exp_month + exp_year for duplicate detection (never stores PAN).

Authentication Methods

JWT Tokens
API Keys
Client Secrets

Use Case: Dashboard, merchant portals

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Access Token: 24-hour expiry
Refresh Token: 7-day expiry
Algorithm: HS256 (HMAC-SHA256)

Use Case: Server-to-server integration

X-API-Key: pk_live_abc123def456...

Production: pk_live_... (64 random chars)
Test: pk_test_... (64 random chars)
Storage: SHA-256 hashed in database

Use Case: Browser checkout (Payment Intents)

X-Client-Secret: pi_abc123_secret_def456...

Format: pi_{intent_id}_secret_{random}
Expiry: 1 hour
Purpose: Authenticate customers without exposing API keys

Deployment Architecture

Production Environment

Live Platform

Hosted on AWS EC2 with Kubernetes orchestration

Infrastructure:

Cloud Provider: AWS
Instance Type: EC2 (Auto-scaling enabled)
Orchestration: Kubernetes (k3d cluster)
Ingress: NGINX Ingress Controller with Cloudflare Tunnel
TLS: Cloudflare SSL termination
Monitoring: Prometheus + Grafana (NodePort access)

Network Architecture

Internet → Cloudflare Tunnel → NGINX Ingress (NodePort 30080)
  ↓
API Gateway (ClusterIP :8080)
  ↓
Public Services (Auth, Merchant, Payment)
  ↓
Internal Services (Tokenization, Transaction)
  ↓
Databases (PostgreSQL, Redis)

Zero-Trust Networking: All pod-to-pod communication is secured by Kubernetes NetworkPolicies with deny-all-by-default rules.

What’s Next?

Quick Start

Create your first payment intent in 5 minutes

Auth API

User registration, login, and API key management

Merchant API

Manage merchant accounts and team members

Payment API

Process payments, refunds, and manage transactions

Support & Resources

GitHub Repository

View source code and report issues

Email Support

Contact for technical support

Kubernetes Guide

Deploy to production with K8s

CLI Tool

Command-line interface for testing

Version: 1.0.0
Last Updated: January 2026
Status: Production Ready

Get Started

API

Integrations

Tools

Documentation Index

​Welcome to Payment Gateway

​What is Payment Gateway?

Microservices Architecture

PCI-DSS Compliance

Financial Operations

Production Practices

​Key Features

​Payment Operations

​Security & Compliance

​Developer Experience

​System Architecture

​High-Level Overview

​Service Architecture Layers

External Layer

Public Layer

Internal Layer

​Service Overview

​1. API Gateway (Port 8080)

​2. Auth Service (Port 8001, gRPC: 50051)

​3. Merchant Service (Port 8002)

​4. Payment API Service (Port 8004)

​5. Tokenization Service (Port 50052 - gRPC Only)

​6. Transaction Service (Port 50053 - gRPC Only)

​7. Payment Checkout (Port 3000)

​Complete Payment Flow

​Flow Breakdown

​Technology Stack

​Backend Services

Language

HTTP Framework

gRPC

ORM

​Data Layer

Database

Cache

​Security

Authentication

Encryption

Hashing

Secrets

​Infrastructure

Orchestration

Ingress

Monitoring

Cloud

​Frontend

Framework

Styling

​Database Architecture

​Redis Usage

​Security & Compliance

​PCI-DSS Compliance

​Encryption Strategy

​Authentication Methods

​Deployment Architecture

​Production Environment

Live Platform

​Network Architecture

​What’s Next?

Quick Start

Auth API

Merchant API

Payment API

​Support & Resources

GitHub Repository

Email Support

Kubernetes Guide

CLI Tool

Welcome to Payment Gateway

What is Payment Gateway?

Key Features

Payment Operations

Security & Compliance

Developer Experience

System Architecture

High-Level Overview

Service Architecture Layers

Service Overview

1. API Gateway (Port 8080)

2. Auth Service (Port 8001, gRPC: 50051)

3. Merchant Service (Port 8002)

4. Payment API Service (Port 8004)

5. Tokenization Service (Port 50052 - gRPC Only)

6. Transaction Service (Port 50053 - gRPC Only)

7. Payment Checkout (Port 3000)

Complete Payment Flow

Flow Breakdown

Technology Stack

Backend Services

Data Layer

Security

Infrastructure

Frontend

Database Architecture

Redis Usage

Security & Compliance

PCI-DSS Compliance

Encryption Strategy

Authentication Methods

Deployment Architecture

Production Environment

Network Architecture

What’s Next?

Support & Resources