Olympus Pay System Documentation

Olympus Pay is a neobank platform for African SMBs, built on Supabase (Postgres + Edge Functions + Auth) and operating under the supervision of the Bank of Botswana Regulatory Sandbox. This document covers architecture, data models, security, provider integrations, and deployment.

At a Glance

Architecture

Olympus Pay uses a serverless, edge-first architecture. All client requests pass through Supabase's embedded Kong API Gateway before reaching edge functions or the PostgREST database layer.

Mobile / Web App (Expo)
        ↓ HTTPS
Kong API Gateway  ←── JWT validation, CORS, rate limiting, TLS
        ↓
  ┌─────┴──────────────────────────┐
  │                                │
PostgREST                  Edge Functions (Deno)
(tables, RPCs)              (business logic)
  │                                │
  └────────┬───────────────────────┘
           │
      PostgreSQL 15 (RLS enforced)
           │
    ┌──────┴──────────────────────────────────────────┐
    │                                                  │
External Providers                            Cloudflare R2
(Zenus, DIDIT, Duffel,                       (file storage)
 Flutterwave, Africa's Talking,
 Documenso, Resend, HotelBeds)

Request Flow

Technology Stack

Database Schema

All tables live in the public schema of a PostgreSQL 15 database. Row-Level Security (RLS) is enabled on every table. The auth.uid() function identifies the current user.

Core Tables

Row-Level Security

Every table has RLS enabled. The general policy is: a user can only read and write their own rows. Financial write operations additionally require KYC approval.

KYC Gate Policy

Sensitive tables like transactions, cards, and scheduled_payments use an additional policy function:

CREATE POLICY "kyc_required" ON transactions
  FOR INSERT TO authenticated
  USING (is_kyc_approved(auth.uid()));

CREATE FUNCTION is_kyc_approved(uid uuid) RETURNS boolean AS $$
  SELECT kyc_status = 'approved'
  FROM profiles WHERE id = uid;
$$ LANGUAGE sql SECURITY DEFINER;

File Storage (Cloudflare R2)

Olympus Pay uses Cloudflare R2 for all file storage. Files are uploaded directly via presigned URLs, keeping storage credentials server-side at all times.

Upload Flow

Storage Buckets (Key Prefixes)

Authentication

Olympus Pay uses Supabase GoTrue for authentication. All sessions are token-based — access tokens are short-lived (1 hour) and are refreshed silently using a long-lived refresh token (30 days). There are no cookies or server-side sessions.

Sign Up

POST /auth/v1/signup — creates a new user and returns an active session immediately. A confirmation email is sent if email confirmation is enabled.

{
  "email": "user@example.com",
  "password": "••••••••",
  "data": {
    "full_name": "Kefilwe Moagi",
    "phone": "+26771234567"
  }
}

Sign In

POST /auth/v1/token?grant_type=password — authenticates with email and password. Returns access_token, refresh_token, and the user object.

{
  "email": "user@example.com",
  "password": "••••••••"
}

// Response
{
  "access_token": "eyJhbGci...",
  "refresh_token": "v1:...",
  "expires_in": 3600,
  "token_type": "bearer",
  "user": { "id": "uuid", "email": "...", "role": "authenticated" }
}

Refresh Token

POST /auth/v1/token?grant_type=refresh_token — exchanges a refresh token for a new access token. The Supabase JS and React Native clients handle this automatically.

{
  "refresh_token": "v1:..."
}

Token Structure

Every access token is a signed JWT. The claims most relevant to edge functions:

Required Headers

Every API request must carry both headers. Kong rejects requests missing either one.

Authorization: Bearer <access_token>
apikey: <supabase_anon_key>

Auth Errors

KYC Flow

Identity verification is a hard gate on all financial operations — sending money, issuing cards, bulk payments, and scheduled payments all require kyc_status = 'approved'. This is enforced both at the RLS level in the database and within edge functions before any external call is made.

Verification is handled by DIDIT and covers three layers: liveness detection (biometric selfie check), document verification (passport, national ID, or driver's licence via OCR + authenticity checks), and AML screening (global sanctions, PEP, and adverse media checks).

Entity Types

Verification Flow

Session Request

POST /functions/v1/didit-session
{
  "entity_type": "individual",  // or "business"
  "country": "BW"               // ISO 3166-1 alpha-2
}

// Response
{
  "session_id": "did_sess_...",
  "session_url": "https://verify.didit.me/session/...",
  "expires_at": "2026-06-15T22:00:00Z"
}

Webhook Payload

POST /functions/v1/didit-webhook
Headers: x-didit-signature: sha256=...

{
  "event": "session.completed",
  "session_id": "did_sess_...",
  "status": "approved",
  "liveness_score": 0.99,
  "document_type": "PASSPORT",
  "document_country": "BW",
  "aml_hits": 0,
  "completed_at": "2026-06-15T21:47:33Z"
}

KYC Status Reference

AML & Screening

DIDIT runs AML checks against the following sources as part of every verification session:

• OFAC Specially Designated Nationals (SDN) list
• UN Security Council consolidated sanctions list
• EU and UK financial sanctions registers
• Politically Exposed Persons (PEP) global database
• Adverse media screening (negative news)

An aml_hits count greater than zero is recorded in kyc_verifications and triggers a compliance_alerts entry for manual review. The user's kyc_status is set to rejected until the alert is resolved.

Account Tiers

Every account operates within a tier that defines transaction limits and feature access. Tier limits are enforced inside edge functions before any call is made to Zenus — a payment that would breach a tier limit is rejected at the application layer, not the banking rail.

Tier Upgrades

Tier changes are applied via the set_account_tier RPC. Upgrades require a verified identity (kyc_status = 'approved'); downgrades take effect immediately.

POST /rest/v1/rpc/set_account_tier
{
  "user_id": "uuid",
  "tier": "business"
}

Compliance

Olympus Pay is a regulated financial institution operating under the supervision of the Bank of Botswana Regulatory Sandbox. Compliance controls are embedded at every layer of the stack — from database policies to edge function logic to third-party provider checks.

Controls

Suspicious Activity

Transactions that trigger a compliance flag from Zenus or exceed monitored thresholds result in a record in compliance_alerts with a severity level (low, medium, high). High-severity alerts are escalated to Suspicious Activity Reports (SARs) and filed with the Bank of Botswana in accordance with applicable financial intelligence obligations.

Edge Functions Overview

53 Deno edge functions handle all business logic. They run on Supabase's global edge network and share common utilities from supabase/functions/_shared/.

Shared Utilities

All edge functions import from supabase/functions/_shared/.

_shared/security.ts

_shared/flutterwave.ts

Handles Flutterwave OAuth2 client credentials flow. getFWToken() fetches and caches a bearer token using FW_CLIENT_ID and FW_CLIENT_SECRET from Vault.

_shared/zenus.ts

Zenus API client. Handles authentication with ZENUS_BEARER_TOKEN and ZENUS_API_KEY. Provides typed request/response interfaces for all Zenus operations.

Banking

Olympus Pay is a regulated financial institution operating under the supervision of the Bank of Botswana Regulatory Sandbox. Cross-border payments, multi-currency accounts, and card issuance are delivered through our partnership with Zenus / TUUM — giving African SMBs access to global payment rails from a single platform.

Banking Structure

Payment Rails

Card Lifecycle

Payments

Send Payment Request

The send-payment-request function creates a Flutterwave payment link and emails it to the recipient via Resend. A hosted payment page at olympuspay.co/pay-request?id=... is also generated for each request.

Bulk Payments (Payroll)

zenus-bulk-payment processes multiple recipients in a single batch call. Each recipient is processed individually and results are returned per-entry. The batch is recorded in the bulk_payments table.

Scheduled Payments

Scheduled payments are stored in scheduled_payments and triggered by a Supabase cron job (pg_cron) that runs daily at 06:00 UTC. The cron job calls the process_scheduled_payments RPC for any payments due that day.

KYC — DIDIT

Three functions handle the full identity verification lifecycle:

Travel — Duffel

Flight search, booking, and management via Duffel API v2. All requests include the Duffel-Version: v2 header.

Flight Booking Flow

Messaging — Africa's Talking

Storage — Cloudflare R2

AI & Tools

Provider Integration Map

Webhooks

All inbound webhooks are verified with HMAC-SHA256 using secrets stored in Supabase Vault. Requests with invalid signatures return 403 Forbidden.

Environment Variables

All secrets are managed via Supabase Vault and injected into edge functions at runtime.

Core (Required)

Banking

KYC

Payments & Messaging

Storage & Travel

Deploy Guide

Edge Functions

# Deploy all edge functions
supabase functions deploy --no-verify-jwt zenus-webhook didit-webhook duffel-webhook documenso-webhook

# Deploy a single function (most functions verify JWT inside the handler)
supabase functions deploy zenus-payment

# Set secrets (from .env file)
supabase secrets set --env-file .env

Database Migrations

# Apply pending migrations
supabase db push

# Generate migration from schema changes
supabase db diff --schema public -f migration_name

Web App (Vercel)

# Build Expo for web
npx expo export --platform web

# Deploy (from project root)
vercel --prod

Local Development

# 1. Clone and install
git clone git@github.com:olympuspay/olympus-app.git
cd olympus-app
npm install

# 2. Start Supabase locally
supabase start

# 3. Copy environment
cp .env.example .env
# Fill in your API keys

# 4. Start the app
npx expo start

# 5. Serve edge functions locally
supabase functions serve

Regulatory

Olympus Pay (Botswana) is a regulated financial institution operating under the supervision of the Bank of Botswana Regulatory Sandbox. All platform operations, integrations, and data handling practices are designed and maintained in alignment with the obligations set forth under this regulatory framework.

Compliance Obligations