Payment API Proxy - Supabase Edge Functions

A multi-provider payment gateway built with Supabase Edge Functions, supporting Daimo Pay and Aqua payment providers with automatic withdrawal integration.

🏗️ Architecture Overview

This service is deployed as Supabase Edge Functions with the following structure:

supabase/
├── functions/
│   ├── payment-api/           # Payment creation & retrieval
│   ├── webhook-handler/       # Daimo & Aqua webhook processing  
│   ├── api-health/            # System health & provider status
│   └── shared/               # Shared utilities & types
├── migrations/              # Database schema & tables
└── config.toml             # Supabase configuration

🚀 Edge Functions

Function	Endpoint	Description
`payment-api`	`/functions/v1/payment-api`	Create payments, get payment status
`webhook-handler`	`/functions/v1/webhook-handler`	Process Daimo/Aqua webhooks, trigger withdrawals
`api-health`	`/functions/v1/api-health`	System health, provider status

🗄️ Database Schema

PostgreSQL (Supabase built-in)
Row Level Security (RLS) enabled
Real-time subscriptions for payment updates
Optimized indexes for performance
CHECK constraints for data integrity

📋 Prerequisites

Supabase CLI installed
Deno runtime installed
Supabase Project created
API Keys for Daimo and Aqua providers

Install Supabase CLI

# macOS
brew install supabase/tap/supabase

# Windows (via scoop)
scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase

# npm (cross-platform)
npm install -g supabase

Install Deno

# macOS/Linux
curl -fsSL https://deno.land/install.sh | sh

# Windows
iwr https://deno.land/install.ps1 -useb | iex

🚀 Deployment Guide

Step 1: Initialize Supabase Project

# Clone this repository
git clone <your-repo-url>
cd payment-api-proxy

# Initialize Supabase
supabase init

# Link to your Supabase project
supabase link --project-ref <your-project-ref>

# Login to Supabase (if not already)
supabase login

Step 2: Set Environment Variables

Create environment secrets in your Supabase dashboard or use CLI:

# Core Configuration
supabase secrets set NODE_ENV=production
supabase secrets set CORS_ORIGINS="https://yourapp.com,https://yourdomain.com"

# Daimo Provider
supabase secrets set DAIMO_API_KEY="your-daimo-api-key"
supabase secrets set DAIMO_BASE_URL="https://pay.daimo.com"
supabase secrets set DAIMO_WEBHOOK_TOKEN="your-daimo-webhook-token"

# Aqua Provider  
supabase secrets set AQUA_BASE_URL="https://api.aqua.network"
supabase secrets set AQUA_API_TOKEN="your-aqua-api-token"
supabase secrets set AQUA_WEBHOOK_TOKEN="your-aqua-webhook-token"

# Withdrawal Integration
supabase secrets set WITHDRAWAL_API_BASE_URL="https://proj-ref.supabase.co"
supabase secrets set WITHDRAWAL_API_JWT_TOKEN="your-withdrawal-jwt-token"
supabase secrets set WITHDRAWAL_INTEGRATION_ENABLED="true"

# Optional: Logging & Monitoring
supabase secrets set LOG_LEVEL="info"
supabase secrets set ENABLE_REQUEST_LOGGING="true"

Step 3: Deploy Database Schema

# Run database migrations
supabase db push

# Verify tables created
supabase db status

Step 4: Deploy Edge Functions

# Deploy all functions
supabase functions deploy payment-api
supabase functions deploy webhook-handler  
supabase functions deploy api-health

# Or deploy all at once
supabase functions deploy

Step 5: Configure Database Policies

# Apply Row Level Security policies
supabase db reset --linked

Step 6: Test Deployment

# Test health check
curl https://<your-project-ref>.supabase.co/functions/v1/api-health

# Test payment creation
curl -X POST https://<your-project-ref>.supabase.co/functions/v1/payment-api \
  -H "Content-Type: application/json" \
  -d '{
    "display": {
      "intent": "Test payment",
      "currency": "USD"
    },
    "destination": {
      "destinationAddress": "0x1234567890abcdef1234567890abcdef12345678",
      "chainId": "10",
      "amountUnits": "1000000",
      "tokenAddress": "0xA0b86a33E6441c8C06DD2a8e8B4A6a0b0b1b1b1b"
    }
  }'

🔧 Local Development

Start Local Development Server

# Start Supabase locally (includes database + edge functions)
supabase start

# Your local endpoints will be:
# API: http://localhost:54321
# Database: postgresql://postgres:postgres@localhost:54322/postgres
# Functions: http://localhost:54321/functions/v1/

Develop Functions Locally

# Serve functions locally with hot reload
supabase functions serve

# Test local function
curl http://localhost:54321/functions/v1/api-health

Local Database Management

# Reset local database
supabase db reset

# View database in browser
supabase dashboard db

📡 API Endpoints

Payment API

Create Payment

POST /functions/v1/payment-api
Content-Type: application/json

{
  "display": {
    "intent": "Coffee purchase",
    "currency": "USD"
  },
  "destination": {
    "destinationAddress": "0x742d35Cc6634C0532925a3b8D6Cd1C3b5123456",
    "chainId": "10",
    "amountUnits": "5500000",
    "tokenAddress": "0xA0b86a33E6441c8C06DD2a8e8B4A6a0b0b1b1b1b"
  },
  "metadata": {
    "orderId": "12345"
  }
}

Get Payment by ID

GET /functions/v1/payment-api/{paymentId}

Get Payment by External ID

GET /functions/v1/payment-api/external-id/{externalId}

Webhook Handler

Daimo Webhook

POST /functions/v1/webhook-handler?provider=daimo&token=your-webhook-token
Content-Type: application/json
X-Daimo-Signature: sha256=...

{
  "type": "payment_completed",
  "paymentId": "payment_123",
  "chainId": 10,
  "txHash": "0x...",
  "payment": { ... }
}

Aqua Webhook

POST /functions/v1/webhook-handler?provider=aqua&token=your-webhook-token
Content-Type: application/json

{
  "invoice_id": "aqua_invoice_123",
  "status": "paid",
  "amount": 100.50,
  "address": "GXXXXXXX...",
  "token_id": "usdc",
  "transaction_hash": "stellar_tx_hash"
}

Health Check

GET /functions/v1/api-health

# Response
{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "database": "connected",
  "providers": {
    "daimo": {
      "status": "healthy",
      "responseTime": 150,
      "lastCheck": "2024-01-01T00:00:00.000Z"
    },
    "aqua": {
      "status": "healthy", 
      "responseTime": 200,
      "lastCheck": "2024-01-01T00:00:00.000Z"
    }
  },
  "withdrawal_integration": {
    "status": "healthy",
    "enabled": true
  }
}

🗄️ Database Schema

Tables

payments

CREATE TABLE payments (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  amount DECIMAL(20,8) NOT NULL CHECK (amount > 0),
  currency TEXT NOT NULL,
  status payment_status NOT NULL DEFAULT 'payment_unpaid',
  external_id TEXT,
  withdraw_id TEXT,
  provider_name TEXT NOT NULL,
  chain_id TEXT NOT NULL,
  created_at TIMESTAMPTZ DEFAULT now(),
  updated_at TIMESTAMPTZ DEFAULT now(),
  status_updated_at TIMESTAMPTZ DEFAULT now(),
  provider_response JSONB,
  metadata JSONB,
  original_request JSONB NOT NULL
);

Payment Status Enum

CREATE TYPE payment_status AS ENUM (
  'payment_unpaid',
  'payment_started', 
  'payment_completed',
  'payment_bounced',
  'payment_refunded'
);

Optimized Indexes

-- Main status query optimization
CREATE INDEX idx_payments_status_created_at ON payments(status, created_at DESC);

-- Unique external_id constraint
CREATE UNIQUE INDEX idx_payments_external_id_unique ON payments(external_id) WHERE external_id IS NOT NULL;

-- Stale payment detection
CREATE INDEX idx_payments_status_status_updated ON payments(status, status_updated_at);

-- Provider and chain specific queries
CREATE INDEX idx_payments_provider_status ON payments(provider_name, status);
CREATE INDEX idx_payments_chain_status ON payments(chain_id, status);

-- Partial indexes for specific status values
CREATE INDEX idx_payments_status_unpaid ON payments(created_at DESC) WHERE status = 'payment_unpaid';
CREATE INDEX idx_payments_status_started ON payments(created_at DESC) WHERE status = 'payment_started';
CREATE INDEX idx_payments_status_completed ON payments(created_at DESC) WHERE status = 'payment_completed';

Row Level Security (RLS)

payments: Public read access for valid payment IDs
Real-time: Enabled for payment status updates
API Keys: Function-level authentication

🔄 Automatic Withdrawal Integration

Flow

USDC Stellar Payment Completed (Webhook)
    ↓
Eligibility Check (USDC + Stellar + Aqua provider)
    ↓
POST to External Withdrawal API
    ↓
Save withdraw_id to payment record
    ↓
Log Success/Failure

Supported Conversions

USDC Stellar → USDC Base ✅
Future: USDC Stellar → USDC Solana

📊 Monitoring & Observability

Logs

# View function logs
supabase functions logs payment-api
supabase functions logs webhook-handler
supabase functions logs api-health

# Real-time logs
supabase functions logs --follow

Metrics

Function invocation count
Error rates
Response times
Database query performance
Provider health status

Alerts

Payment processing failures
Webhook delivery failures
Provider API downtime
Withdrawal integration errors

🔒 Security Features

Authentication & Authorization

API Key Authentication: For payment creation
Webhook Verification: Signature validation (Daimo) + Token auth (Aqua)
Row Level Security: Database-level access control
CORS: Configurable allowed origins

Rate Limiting

Built-in: Supabase Edge Functions rate limiting
Custom: Additional rate limiting for webhook endpoints
DDoS Protection: Supabase infrastructure-level protection

Data Integrity

CHECK constraints: Amount must be positive
Unique constraints: External IDs are unique
Input validation: Application-level validation
Type safety: TypeScript throughout

🚀 Production Checklist

Pre-Deployment

Environment secrets configured
Database migrations applied
Database improvements applied (./apply-db-improvements.sh)
RLS policies enabled
CORS origins configured
API keys obtained from providers

Post-Deployment

Ongoing Maintenance

Monitor function performance
Review error logs regularly
Update provider API configurations
Scale function resources as needed
Regular database maintenance
Monitor index usage

🔧 Troubleshooting

Common Issues

Function Deployment Fails

# Check function syntax
deno check supabase/functions/payment-api/index.ts

# View deployment logs
supabase functions logs payment-api --level error

Database Connection Issues

# Check database status
supabase db status

# Reset database
supabase db reset --linked

Provider API Errors

# Test provider connectivity
curl -H "Authorization: Bearer $DAIMO_API_KEY" https://pay.daimo.com/health

# Check environment secrets
supabase secrets list

Webhook Processing Failures

# View webhook logs
supabase functions logs webhook-handler

# Test webhook manually
curl -X POST http://localhost:54321/functions/v1/webhook-handler?provider=daimo \
  -H "Content-Type: application/json" \
  -d '{"type":"payment_completed","paymentId":"test"}'

📚 Additional Resources

🤝 Contributing

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Test locally with supabase start
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open Pull Request

Development Guidelines

Use TypeScript for all new code
Follow existing code patterns
Add tests for new functionality
Update documentation for API changes
Use conventional commit messages

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🚀 Quick Start Commands

# Complete deployment in one go
git clone <repo> && cd payment-api-proxy
supabase init && supabase link --project-ref <your-ref>
supabase secrets set DAIMO_API_KEY="your-key" AQUA_API_TOKEN="your-token"
supabase db push && supabase functions deploy
curl https://<your-ref>.supabase.co/functions/v1/api-health

You're now ready to process payments through multiple blockchain networks with automatic withdrawal integration! 🎉

Name		Name	Last commit message	Last commit date
Latest commit History 36 Commits
docs		docs
supabase		supabase
.gitignore		.gitignore
.prettierrc		.prettierrc
LICENSE		LICENSE
README.md		README.md
env.dev		env.dev
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

License

RozoAI/api-proxy

Folders and files

Latest commit

History

Repository files navigation

Payment API Proxy - Supabase Edge Functions

🏗️ Architecture Overview

🚀 Edge Functions

🗄️ Database Schema

📋 Prerequisites

Install Supabase CLI

Install Deno

🚀 Deployment Guide

Step 1: Initialize Supabase Project

Step 2: Set Environment Variables

Step 3: Deploy Database Schema

Step 4: Deploy Edge Functions

Step 5: Configure Database Policies

Step 6: Test Deployment

🔧 Local Development

Start Local Development Server

Develop Functions Locally

Local Database Management

📡 API Endpoints

Payment API

Create Payment

Get Payment by ID

Get Payment by External ID

Webhook Handler

Daimo Webhook

Aqua Webhook

Health Check

🗄️ Database Schema

Tables

payments

Payment Status Enum

Optimized Indexes

Row Level Security (RLS)

🔄 Automatic Withdrawal Integration

Flow

Supported Conversions

📊 Monitoring & Observability

Logs

Metrics

Alerts

🔒 Security Features

Authentication & Authorization

Rate Limiting

Data Integrity

🚀 Production Checklist

Pre-Deployment

Post-Deployment

Ongoing Maintenance

🔧 Troubleshooting

Common Issues

Function Deployment Fails

Database Connection Issues

Provider API Errors

Webhook Processing Failures

📚 Additional Resources

🤝 Contributing

Development Guidelines

📄 License

🚀 Quick Start Commands

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages