BorderCash Overview
BorderCash is a self-hosted, white-label fintech platform for cross-border payments, digital wallet management, and tokenized asset investment. It uses a central custody model backed by USDC on the Stellar network to deliver accounts, payments, and utility services from infrastructure you operate yourself.
This document explains what the product is and how it is built. For installation, configuration, and day-to-day operation, see BorderCash Usage. For commercial licensing and feature tier overviews, visit the BorderCash Product Page.
1. Positioning
BorderCash is designed for organisations that need a regulated-style financial surface without outsourcing the ledger:
- Enterprises that must keep custody of customer funds inside their own perimeter.
- Developers who want a complete, self-hostable fintech backend and client rather than a black-box API.
- Distributors who need to rebrand the platform as their own product.
BorderCash is a commercial, licensed product. There is no unlicensed or community mode. Every deployment must present a valid Pluggedspace licence; see Licensing and lifecycle.
2. Product principles
| Principle | What it means in practice |
|---|---|
| Central custody | User balances are held as internal ledger records, not scattered self-custodied accounts. Each user has a wallet record plus per-currency accounts. |
| Stellar + USDC settlement | On-chain settlement uses Stellar and USDC, chosen for low fees and fast finality. |
| Self-hosted | You run the database, broker, workers, and web tier. No BorderCash-operated backend is in the request path. |
| White-label by configuration | Brand name, legal entity, logo, colours, support contacts, and terms links are database records, not code edits. |
| Ledger integrity first | Every movement is written to an append-only transaction log and reconciled by the DRAC module. |
| Fail safe, never fail shut | An unlicensed or misconfigured node still boots and serves reads so it can be diagnosed, but refuses writes. |
3. Module tour
Features are grouped into modules that an operator can enable or disable at runtime from the admin console. Nothing requires a rebuild or redeploy.
3.1 Accounts and banking
- Multi-currency wallets - per-user records with a base USD balance and local currency conversion.
- Virtual IBAN accounts (EUR/GBP) - generate and manage virtual accounts for receiving fiat.
- African NUBAN accounts - dedicated African virtual accounts for local transfers.
- Mobile Money - M-Pesa, MTN MoMo, and Airtel deposit and withdrawal rails.
- Banking cards - card presentation and IBAN/SWIFT details in the client.
3.2 Payments
- Fiat on/off-ramps - bank transfers, Transak, and Railsr integrations.
- Crypto deposits and swaps - Changelly-backed crypto deposit and withdrawal.
- P2P transfers - user-to-user transfers with transaction PIN confirmation.
- Transaction ledger - every movement recorded with type, status, and audit fields.
3.3 Investments
- Tokenized stock market - browse, buy, and sell tokenized equities.
- Portfolio tracking - holdings, cost basis, and profit/loss per user.
- Pluggable brokerage - the engine is selectable: Stellar DEX (tokenized assets),
Alpaca Markets (real US equities), or Alpha Vantage (market data only). Switched
by an admin setting; there is no API for it. The instrument catalogue is populated by
manage.py sync_instrumentsrather than entered by hand - automatically from Alpaca, or from a curated registry file for Stellar. See Brokerage providers. - Fractional trading - optional, enabled per deployment.
3.4 Commerce and utilities
- Shop - product catalogue, categories, cart, shipping, and checkout.
- Airtime top-up - prepaid mobile airtime across supported operators.
- Data bundles - mobile data packages.
- Utility bill payment - recurring bills via configured providers.
- Gift cards - purchase digital gift cards by country and brand.
Beta status. Utility top-ups (airtime, data, bills) and gift-card fulfilment currently validate requests and return
pending_integration; they do not yet dispatch to live provider APIs. Checkout creates a pending order and clears the cart but does not yet charge a wallet or reserve stock. Treat these as beta until provider credentials are configured. See Known gaps.
3.5 Identity, support, and loyalty
- KYC and onboarding - tiered identity verification with optional enhanced (biometric / government ID) verification.
- 2FA - optional enforcement of OTP at login.
- Monica disputes - users raise and track grievances; staff triage and resolve.
- Points and rewards - loyalty accrual, referral codes, and redemption.
3.6 Compliance and operations (DRAC)
- Anomaly detection - flags suspicious patterns for review.
- Reconciliation - internal accounting checks between ledger and custody.
- Audit log - tamper-evident record of privileged actions.
- Compliance checks - configurable control evaluation.
4. Architecture
4.1 Stack
| Layer | Technology |
|---|---|
| Language | Python 3.10+ |
| Web framework | Django 5.1+ with Django REST Framework |
| Task queue | Celery with Redis as broker |
| Database | PostgreSQL |
| Real-time | Django Channels (WebSockets) |
| Authentication | SimpleJWT bearer tokens |
| Blockchain | Stellar network (USDC) |
| Object storage | Dropbox via django-storages (configurable) |
| Client | Flutter (web, desktop, mobile) |
| Deployment | Docker and Docker Compose |
4.2 Runtime services
A standard deployment runs five services:
| Service | Role |
|---|---|
web | Django + Gunicorn HTTP/API server |
celery_worker | Background task execution |
celery_beat | Scheduled task dispatch |
db | PostgreSQL |
redis | Cache and Celery broker |
Canonical backend port: 8000. The same port is used for local development,
Docker, CI, packaged artifacts, and client defaults.
4.3 Application domains
The Django project (swif) is composed of focused apps:
| App | Responsibility |
|---|---|
app | Core domain: users, wallets, transactions, fees, and the Shop/Utilities API |
kyc | Identity verification workflows |
iban | Virtual IBAN and card records |
invest | Tokenized stocks, portfolios, and brokerage integration |
monica | Disputes and support |
drac | Anomaly detection, reconciliation, audit, compliance |
backup | Backup jobs and upload tracking |
licensing | Pluggedspace licence verification |
4.4 API surface
| Prefix | Purpose |
|---|---|
/api/ | Core account, wallet, and transaction endpoints |
/api/v1/banking/ | Banking-specific operations |
/api/v1/config/ | White-label branding, module flags, and banking rails |
/api/v1/node/ | Node identity and licence status |
/kyc/ | KYC submissions and status |
/iban/ | Virtual account and card management |
/invest/ | Portfolio, stock catalogue, and trading |
/m/ | Monica disputes |
/util/ | Shop, cart, checkout, utilities, gift cards |
/healthz, /livez, /readyz | Health, liveness, readiness |
/swagger/, /redoc/ | Generated OpenAPI documentation |
The /api/v1/config/ endpoints are public and deliberately return no secrets -
only branding, enabled modules, and active banking rails.
5. White-labeling
Two singleton configuration records drive rebranding.
Organization & Branding Configuration controls identity and appearance:
- Organization name, legal entity name
- Logo and favicon URLs
- Primary, secondary, and accent colour tokens
- Support email and phone
- Website, Terms of Service, and Privacy Policy URLs
Provider & API Secret Configuration holds third-party credentials, encrypted at rest in the database and never returned over the public configuration API.
Client-side brand colours can additionally be overridden at build time, for example:
flutter build web --dart-define=PRIMARY_COLOR=0xFF1E3A8A \
--dart-define=ACCENT_COLOR=0xFF10B981
Because branding lives in the database, a single deployment can be re-skinned without rebuilding the client.
6. Licensing and lifecycle
BorderCash validates its licence against the Pluggedspace registry.
| Setting | Purpose |
|---|---|
PLUGGEDSPACE_LICENSE_ENGINE_URL | Registry base URL, https://registry.pluggedspace.org |
PLUGGEDSPACE_LICENSE_TOKEN | The signed licence bundle issued to your deployment |
PLUGGEDSPACE_PUBLIC_KEY | Ed25519 public key the token is verified against |
PLUGGEDSPACE_API_KEY | Registry API credential where required |
PLUGGEDSPACE_DEPLOYMENT_ID | Unique identifier for this node |
6.1 Behaviour with a valid licence
Requests flow normally. Responses carry:
X-Pluggedspace-Plan: <plan>X-Pluggedspace-Status: active
6.2 Behaviour without a valid licence
The node still boots. It continues to serve GET, HEAD, and OPTIONS, plus
/admin/, /healthz, /api/v1/node/, and /api/token/, so an operator can diagnose
and renew. Every POST, PUT, PATCH, and DELETE returns 403:
{
"error": "License Required",
"status": "read_only_maintenance",
"status_code": 403
}
There are two ways to reach this state:
- No token configured - reported as
License Required. - A placeholder token (
paste_your_...,your_...,changeme) - fails signature verification and behaves identically. This is the more dangerous case because it reads like a credentials problem rather than a licensing one.
Both are caught at startup by the system check framework:
| Check | Meaning |
|---|---|
app.E001 | Licence token is empty or still an unfilled placeholder |
app.E002 | Public key is missing or still the bundled default |
Enforcement is not configurable. There is no environment variable that disables it, because a bypass would let an expired or forged licence write to the ledger. The way out of read-only mode is to install a valid licence.
6.3 Verification is offline
Licence verification is a local Ed25519 signature check. It does not require a network call, so a node keeps enforcing correctly during an outage.
7. Security posture
- Encrypted secrets - provider API credentials are encrypted at rest and masked in the admin interface.
- Transaction PIN - an additional user-held secret required for sensitive operations.
- Least-privilege admin - Django admin permissions are enforced per model; the executive dashboard is read-only.
- Append-only audit - DRAC records privileged actions and anomalies.
- Reconciliation - automated checks detect divergence between the ledger and custody balances.
- Reporting - vulnerabilities should be reported privately to
support@pluggedspace.org. SeeSECURITY.mdin the repository.
8. Where to next
- Official Product Page - BorderCash on Pluggedspace
- Installing, configuring, and operating BorderCash - BorderCash Usage
- Architecture and subsystem internals - BorderCash Architecture & Subsystems, covering the secrets vault, license engine internals, CI/CD pipeline, and lifecycle scripts
- Generated API reference -
/swagger/and/redoc/on any running node - Licence and release distribution - the Pluggedspace registry at
https://registry.pluggedspace.org