Skip to main content

​
Gateway Overview

The OLIVE 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

ClientAuthenticationUse Case
External POSHMAC per-merchantTerminal payments
WhatsApp AgentService authUser operations via chat
Admin DashboardJWTUser and transaction management
Third-party IntegrationsAPI KeysPartner integrations

​
Endpoint Groups

​
Public Endpoints

EndpointDescription
GET /healthGateway and wallet-core health status
GET /versionAPI version information
POST /api/v1/public/subscribersPublic subscriber registration

​
Protected Endpoints

GroupEndpointsAuth Required
SubscribersRegister, lookup, update, blockAPI Key / JWT
CardsLink, block, unblock, upload CSVAPI Key / JWT
WalletBalance, payments, transfersAPI Key / JWT
AgentsLookup, cashin, transferAPI Key / JWT
POSPayment, verify-cardHMAC
ComplianceCheck, alerts, rulesJWT (Admin)
AdminLogin, API keys, audit logsJWT
WebhooksVULT cashinHMAC

​
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