Architecture

System Overview

Loofta Pay uses a multi-provider architecture to handle different payment scenarios:

┌─────────────────────────────────────────────────────────┐
│                    Loofta Pay Platform                    │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ Payment API  │  │  Checkout    │  │  Admin API   │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└─────────────────────────────────────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        │               │               │
┌───────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
│ NEAR Intents │ │  Biconomy   │ │ Rhinestone  │
│ (Cross-chain)│ │(Same-chain) │ │(Smart Accts)│
└──────────────┘ └─────────────┘ └────────────┘
        │               │               │
        └───────────────┼───────────────┘
                        │
            ┌───────────▼───────────┐
            │  Companion Wallets    │
            │  (Intermediate Hops)  │
            └───────────────────────┘

Core Components

Payment Processing Engine

Handles payment request creation, routing, and execution:

• Route Calculation: Determines optimal swap path
• Provider Selection: Chooses best provider for each route
• Status Tracking: Monitors payment lifecycle
• Error Handling: Automatic refunds on failure

Companion Wallet System

Smart accounts that handle complex multi-hop swaps:

• Automatic Creation: Generated per payment when needed
• Intermediate Token Handling: Receives and forwards tokens
• Gas Optimization: Bundles multiple operations
• Dust Sweeping: Collects leftover amounts

Organization Management

Multi-tenant system for businesses:

• Organization Profiles: Custom branding and settings
• Checkout Customization: Logo upload, status management
• Referral Tracking: Monitor payments by organization
• Admin Dashboard: Full management interface

Safety Mechanisms

Distributed processing safeguards:

• Distributed Locks: Prevent concurrent processing
• Idempotency Checks: Verify transaction hashes
• Status Verification: Multi-stage status checks
• Automatic Refunds: Failed payment recovery

Technology Stack

• Framework: Next.js 16 (App Router)
• Language: TypeScript
• Database: Supabase (PostgreSQL)
• Caching: Redis
• Authentication: Privy
• Hosting: Vercel
• Swap Providers:

  • NEAR Intents (Cross-chain swaps)
  • Biconomy (Same-chain bundled transactions)
  • Rhinestone (Smart account modules)

Data Flow

Payment Request Flow

1

Create payment request

User creates payment request via API.

2

Generate link

System generates unique payment link.

3

Payer opens link

Payer opens link and selects payment method.

4

Route calculation

System calculates optimal route.

5

Execute payment

Payment executed via appropriate provider.

6

Track status

Status updated and tracked.

7

Recipient receives funds

Recipient receives funds.

Checkout Flow

1

Access checkout

Customer accesses checkout URL with organizationId.

2

Validate organization

System validates organization and loads branding.

3

Enter payment details

Customer enters payment details.

4

Redirect to processing

Redirects to payment processing with organization context.

5

Process payment

Payment processed with orgReferral tracking.

6

Log payment

Payment logged with organization reference.

Companion Wallet Flow

1

Detect multi-hop need

System detects need for multi-hop swap.

2

Create or retrieve wallet

Companion wallet created or retrieved.

3

First hop

User token → Intermediate token (to companion).

4

Second hop

Intermediate token → Final token (from companion).

5

Final execution

Companion wallet executes final transaction.

6

Dust sweeping

Dust swept to treasury.

7

Clear companion wallet

Companion wallet cleared.

Infrastructure

Database Schema

Organizations:

• Organization profiles and settings
• Checkout status and branding
• Referral codes for tracking

Users:

• Admin role management
• Access control

Payment Logs:

• Transaction history
• Status tracking
• Organization references

Caching Layer

Redis used for:

• Distributed locks
• Pending payment tracking
• Companion wallet data
• Rate limiting

Cron Jobs

Unified cron job (/api/cron/process-all) handles:

• Payment processing
• Claim processing
• Swap processing

All jobs include distributed locks and idempotency checks.

Security Architecture

• Non-Custodial: No fund custody
• Distributed Locks: Prevent race conditions
• Idempotency: Prevent duplicate processing
• Status Verification: Multi-stage checks
• Automatic Refunds: Failed payment recovery

See Security & Safety for detailed information.