Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/own-pay/OwnPay-Documentation/llms.txt

Use this file to discover all available pages before exploring further.

Getting OwnPay running locally is straightforward — the quick path uses PHP’s built-in web server, works identically on Windows, macOS, and Linux, and requires no web-server configuration. From a fresh clone to the admin panel takes about two minutes once the prerequisites are installed.
New to the codebase? Read the Architecture guide first to understand the directory structure and request lifecycle before diving into code.

​
Prerequisites

ToolVersionNotes
PHP8.3+Requires: bcmath, json, mbstring, openssl, pdo, pdo_mysql, curl
Composer2.xPHP dependency manager — getcomposer.org
MySQL or MariaDBMySQL 8.0+ / MariaDB 10.4+The only supported database engine
GitAny recent versiongit-scm.com
Node.js20+ (optional)Required only for JS/CSS linting (composer lint)
Verify your PHP version and loaded extensions before proceeding: 
php -v
php -m

​
Quick Start — All Platforms (~2 minutes)

This path works identically on Windows, macOS, and Linux.
1

Clone the Repository

git clone https://github.com/own-pay/OwnPay.git
cd OwnPay
2

Install PHP Dependencies

composer install
3

Create an Empty Database

mysql -u root -p -e "CREATE DATABASE ownpay CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
You don’t need to import any schema manually — the web installer does this for you.
4

Start the Built-in Web Server

php -S localhost:8000 -t public
5

Run the Install Wizard

Open http://localhost:8000 in your browser. You’ll be redirected to the /install wizard, which generates your .env, imports the 48-table schema, and creates your admin account. No manual .env editing required.
The installer writes a lock file at storage/.installed. To re-run the installer, delete that file and drop/recreate the database. Do not delete the lock file on a production installation.

​
Platform-Specific Stacks

Prefer a real web server with pretty *.test domains? These bundled stacks make it easy.
Debian / Ubuntu:
sudo apt update
sudo apt install -y php8.3-cli php8.3-mysql php8.3-mbstring php8.3-bcmath \
                    php8.3-curl php8.3-xml php8.3-zip unzip mariadb-server composer

sudo systemctl start mariadb
sudo mysql -e "CREATE DATABASE ownpay CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

git clone https://github.com/own-pay/OwnPay.git && cd OwnPay
composer install
php -S localhost:8000 -t public
Fedora / RHEL:
sudo dnf install php-cli php-mysqlnd php-mbstring php-bcmath php-json composer mariadb-server
For a production-like Nginx or Apache setup, point the document root at public/ and route all requests to public/index.php. An Apache .htaccess is already included; an nginx.conf.example ships in the repo root.

​
Verify Your Setup

After installation, run the same checks that CI runs. All three must pass on a clean checkout: 
composer test       # PHPUnit — all tests must pass
composer analyse    # PHPStan — must stay at level 9
composer lint       # Twig + JS + CSS lint (Node.js required for JS/CSS)

​
Optional: Gateway Callback Tunneling

External gateways (bKash, Stripe, etc.) cannot reach localhost or *.test domains. To test real redirects and webhooks, expose your local server with a tunnel: 
# Using ngrok (https://ngrok.com/download)
ngrok http 8000
# Then set in .env:
# GATEWAY_CALLBACK_URL=https://<your-id>.ngrok-free.app

​
Troubleshooting

SymptomFix
/install says a PHP extension is missingInstall the listed php-* extension and restart the server. Re-check with php -m.
composer install fails on ext-*Your CLI PHP lacks an extension. Install it (e.g., php8.3-bcmath). Note that the CLI php.ini may differ from the web one.
”Could not connect to database” in the wizardConfirm MySQL is running and the database exists. On macOS/Linux, the default user is often root with an empty password or socket authentication.
Blank page or 500 with no detailSet APP_DEBUG=true in .env for a detailed error page (never in production). Check storage/logs/.
Installer redirects after completionDelete storage/.installed only if you intend to reinstall; otherwise clear storage/cache/.
Permission errors writing .env or storage/Ensure the project root and storage/ are writable by your user or the web-server user.

​
Key Directories for Contributors

DirectoryWhat Lives Here
src/Controller/HTTP handlers for admin, API, checkout, and install routes
src/Service/Business logic — payments, brands, refunds, SMS, devices
src/Repository/Data access layer with TenantScope brand isolation
modules/gateways/Payment gateway adapter plugins
templates/Twig views for admin, checkout, emails, and error pages
config/routes/Route definitions (web.php, api.php)
database/schema.sql and numbered migration files
To explore a payment flow end-to-end, start at src/Controller/Api/PaymentController.php (intent creation) → src/Service/Payment/PaymentService.php (business logic) → src/Gateway/GatewayBridge.php (gateway dispatch) → src/Controller/Webhook/UnifiedWebhookController.php (callback handling).

Build docs developers (and LLMs) love

Get started for freeTalk to us