Troubleshooting - Fix Common Installation and Payment Errors

​

Installation issues

​

Installer won’t open or shows blank page

1. Verify PHP version: php -v (must be 8.3+)
2. Check extensions: php -m | grep -E 'pdo_mysql|openssl|bcmath|mbstring|curl|zip'
3. On shared hosting, go to Software > Select PHP Version and set PHP 8.3

​

Database connection failed

# Test connection
mysql -u YOUR_USER -p -h YOUR_HOST YOUR_DB_NAME

# Check MySQL status
systemctl status mysql

​

storage/ directory not writable

# VPS
chown -R www-data:www-data /var/www/ownpay
chmod -R 775 /var/www/ownpay/storage

# Shared hosting: Set storage/ to 775 via File Manager

​

“Already Installed” message

​

Login issues

​

”Invalid credentials” error

1. Check account status in database: SELECT status FROM op_merchant_users WHERE email = '[email protected]'
2. If suspended, reactivate in People > Staff
3. Reset password via admin panel or database

​

”Account temporarily locked”

• Wait 5 minutes for lockout to expire
• Or admin can clear lockout: DELETE FROM op_login_attempts WHERE email = '[email protected]' AND success = 0

​

Two-factor authentication not working

1. Check server time: date -u
2. Sync NTP: sudo timedatectl set-ntp true
3. If locked out, admin can disable 2FA:
   UPDATE op_merchant_users SET two_factor_enabled = 0, totp_secret_enc = NULL WHERE email = '[email protected]';
   

​

Payment issues

​

Transaction stuck in “pending”

1. Check if cron is running: ls -la storage/cron/
2. Check SMS records: SELECT * FROM op_sms_parsed WHERE match_status = 'pending'
3. Manually trigger cron: php public/index.php cron/run

​

Payment shows “failed” but customer was charged

1. Check gateway dashboard for the transaction
2. If confirmed paid, update manually:
   UPDATE op_transactions SET status = 'completed', completed_at = NOW(6) WHERE trx_id = 'YOUR_TRX_ID';
   
3. Run reconciliation: php public/index.php admin/reconcile --trx=YOUR_TRX_ID

​

Gateway not appearing on checkout

1. Check plugin status: SELECT status, is_active FROM op_plugins WHERE slug = 'gateway-slug'
2. Check gateway config: SELECT enabled FROM op_gateway_configs WHERE merchant_id = YOUR_ID AND gateway_slug = 'gateway-slug'
3. Enable in Gateways > Payment Gateways

​

Webhook issues

​

Webhooks not being delivered

1. Verify URL is public HTTPS: curl -v https://your-endpoint.com/webhooks/ownpay
2. Check delivery logs: SELECT * FROM op_webhook_events WHERE status = 'failed'
3. Use ngrok for local testing: ngrok http 8080

​

Webhook signature verification failing

1. Use the raw request body, never re-encode JSON
2. Verify using HMAC-SHA256: hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret)
3. Compare with hash_equals() for timing-safe comparison

​

Performance issues

​

Admin panel is slow

1. Enable Redis: CACHE_DRIVER=redis in .env
2. Enable OPcache: opcache.enable=1 in php.ini
3. Check slow queries: tail -20 /var/lib/mysql/slow-queries.log

​

High memory usage

1. Reduce pm.max_children in PHP-FPM config
2. Check for memory leaks: valgrind --leak-check=full php public/index.php ...
3. Restart PHP-FPM: systemctl restart php8.3-fpm

​

Getting help

1. Check the FAQ for common questions
2. Search GitHub Issues for known problems
3. Join the Discord community for real-time help
4. Open a GitHub Issue with:
   • OwnPay version (php public/index.php --version)
   • PHP version (php -v)
   • Error message and stack trace
   • Steps to reproduce