Overview

The SmartPay Gateway is a Go-based REST API that serves as the public entry point for all external integrations. It handles authentication, rate limiting, request routing, and proxies requests to the wallet-core service over gRPC.

Purpose

API Surface

REST endpoints for payments, subscribers, cards, agents, compliance, and admin operations

Authentication

Multiple auth methods: API keys, JWT, HMAC, service auth

Security

Rate limiting, input validation, audit logging, and CORS protection

Observability

Structured logging, Prometheus metrics, and Swagger documentation

Who Uses It

Client	Authentication	Use Case
External POS	HMAC per-merchant	Terminal payments
WhatsApp Agent	Service auth	User operations via chat
Admin Dashboard	JWT	User and transaction management
Third-party Integrations	API Keys	Partner integrations

Endpoint Groups

Public Endpoints

Endpoint	Description
GET /health	Gateway and wallet-core health status
GET /version	API version information
POST /api/v1/public/subscribers	Public subscriber registration

Protected Endpoints

Group	Endpoints	Auth Required
Subscribers	Register, lookup, update, block	API Key / JWT
Cards	Link, block, unblock, upload CSV	API Key / JWT
Wallet	Balance, payments, transfers	API Key / JWT
Agents	Lookup, cashin, transfer	API Key / JWT
POS	Payment, verify-card	HMAC
Compliance	Check, alerts, rules	JWT (Admin)
Admin	Login, API keys, audit logs	JWT
Webhooks	VULT cashin	HMAC

Quick Start

With Docker Compose

docker compose up -d --build gateway wallet-core

Build and Run Locally

cd gateway
go build -o gateway ./cmd/server
./gateway -config config.yaml

Verify Health

curl http://localhost:8080/health

Expected response:

{
  "service": "gateway",
  "version": "1.0.0",
  "healthy": true,
  "wallet_core": {
    "healthy": true,
    "version": "1.0.0"
  }
}

API Documentation

Interactive Swagger documentation is available at:

http://localhost:8080/docs

Architecture

Project Structure

gateway/
├── cmd/
│   └── server/
│       └── main.go          # Entry point, route registration
├── internal/
│   ├── auth/                # JWT, API key validation
│   ├── config/              # YAML config loading
│   ├── handler/             # HTTP handlers (17 files)
│   │   ├── subscriber_handler.go
│   │   ├── card_handler.go
│   │   ├── wallet_handler.go
│   │   ├── agent_handler.go
│   │   ├── pos_handler.go
│   │   ├── compliance_handler.go
│   │   └── ...
│   ├── middleware/          # Auth, logging, rate limiting (12 files)
│   ├── utils/               # Helpers and utilities
│   └── wallet/              # gRPC client wrapper
├── docs/                    # Swagger generated docs
├── config.yaml              # Default configuration
└── Dockerfile

Key Features

Idempotent Operations

All payment requests support idempotency via X-Request-ID header:

curl -X POST http://localhost:8080/api/v1/payments \
  -H "Authorization: Bearer API_KEY" \
  -H "X-Request-ID: unique-request-123" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "u123", "recipient": "u456", "amount": 5000}'

Audit Logging

All operations are logged with:

• Request/response details
• User and client identification
• Timestamps and duration
• Operation outcomes

Error Responses

Standard error format:

{
  "error": "Error description",
  "code": "ERROR_CODE",
  "details": {}
}

Next Steps

Authentication

Configure API keys, JWT, and HMAC

Configuration

config.yaml reference

API Reference

Complete endpoint documentation

Architecture

Internal architecture details