MorPOS Payment Gateway for Magento 2

MorPOS Payment Gateway for Magento 2 is a secure and easy-to-use payment gateway extension that integrates the Morpara MorPOS payment system with Magento 2 stores. Customers can complete their orders through a secure Hosted Payment Page (HPP) flow or use an Embedded Payment Form for a seamless checkout experience.

✨ Features

• 🛒 Magento 2 Integration: Seamlessly adds MorPOS as a payment method for Magento 2.2+
• 🔒 Secure Payments: Hosted Payment Page (HPP) and Embedded Payment Form options
• 🌍 Multi-Currency: Supports TRY, USD, EUR currencies
• 💳 Multiple Payment Options: Credit cards, debit cards, and installment payments
• 🧪 Sandbox Mode: Complete test environment for development
• 🔧 Easy Configuration: Simple admin panel setup with connection testing
• 🛡️ Security Features: HMAC-based signature validation, CSP compliance, encrypted credentials
• 🏪 Multi-Store: Configure per store/website with different settings
• 👤 Guest Checkout: Full support for guest orders
• 🌐 Multi-Language: Supports Turkish and English (extensible)

📋 Requirements

Server Requirements

PHP Extensions

• cURL - Required for API communication
• json - Required for data processing
• hash - Required for security signatures
• openssl - Required for secure connections

Magento Features

• Admin Panel Access: Required for module configuration
• Database Access: For conversation tracking table
• HTTPS: Required for production environments

🚀 Installation

Method 1: Via Composer (Recommended)

1. Require the Package

   composer require morpara/morpos-magento2
   

2. Enable the Module

   php bin/magento module:enable MorPOS_PaymentGateway
   

3. Run Setup Commands

   php bin/magento setup:upgrade
   php bin/magento setup:di:compile
   php bin/magento setup:static-content:deploy
   php bin/magento cache:flush
   

Method 2: Manual Installation

1. Download the Module

   • Download the latest release from GitHub Releases

2. Extract to Magento

   # Create directory structure
   mkdir -p app/code/MorPOS/PaymentGateway
   
   # Extract module files
   unzip morpos-magento.zip -d app/code/MorPOS/PaymentGateway
   

3. Enable the Module

   php bin/magento module:enable MorPOS_PaymentGateway
   

4. Run Setup Commands

   php bin/magento setup:upgrade
   php bin/magento setup:di:compile
   php bin/magento setup:static-content:deploy
   php bin/magento cache:flush
   

Method 3: FTP Upload

1. Download the module files from GitHub
2. Extract the ZIP file
3. Using your FTP client, upload the contents to app/code/MorPOS/PaymentGateway/
4. Connect to your server via SSH and run the setup commands from Method 2

⚙️ Configuration

1. Access Settings

Navigate to Stores → Configuration → Sales → Payment Methods → MorPOS Payment Gateway

2. Required Settings

Fill in the following mandatory fields:

Where to get credentials? Contact Morpara Support or visit MorPOS Documentation to obtain your merchant credentials.

3. Environment Settings

Sandbox Mode

• ✅ Enable for development/testing
• Uses sandbox endpoints
• No real transactions processed
• Test card numbers accepted

Form Type Choose your payment interface:

• Hosted Payment Page (Redirect): Redirect to MorPOS payment page (recommended)
  • More secure
  • PCI compliance handled by MorPOS
  • Professional payment interface
• Embedded Payment Form (Modal): Payment form within your site
  • Seamless checkout experience
  • Requires SSL certificate

Order Status Settings

• New Order Status: Status to set when payment succeeds (e.g., "Processing")

Advanced Settings

• Payment from Applicable Countries: Choose "All Allowed Countries" or "Specific Countries"
• Payment from Specific Countries: Select countries if using specific countries option
• Minimum Order Total: Optional minimum order amount
• Maximum Order Total: Optional maximum order amount
• Sort Order: Display order in payment methods list

4. Connection Test

After entering credentials:

1. Click Test Connection button in the admin panel
2. Wait for the connection test to complete
3. Verify success message appears
4. If test fails, check credentials and sandbox mode setting

5. Enable the Payment Method

• Set Enabled to Yes
• Click Save Config to activate MorPOS on your store
• Clear cache: php bin/magento cache:flush

🔧 Payment Flow

Customer Checkout Process

1. Cart Review: Customer reviews items in cart
2. Checkout: Customer proceeds to checkout
3. Payment Selection: Customer selects MorPOS as payment method
4. Payment Initiation:
   • System validates cart and creates order
   • Payment session initiated with MorPOS API
   • Unique conversation ID generated for tracking
5. Payment Processing:
   • Hosted Mode: Customer redirected to MorPOS payment page
   • Embedded Mode: Payment form loads in modal popup
6. Payment Completion:
   • Customer completes payment
   • MorPOS sends callback to store
   • Order status updated automatically
7. Confirmation: Customer sees success/failure page

Security Features

The module implements multiple security layers:

• Credential Encryption: Client Secret and API Key are encrypted in database
• Conversation Tracking: Each payment gets unique tracking ID with HMAC-SHA256
• Signature Verification: All API requests are signed
• CSP Compliance: Automatic Content Security Policy configuration
• HTTPS Only: All API communication uses secure connections
• No Sensitive Logging: Request/response bodies are never logged

Content Security Policy (CSP)

The module automatically whitelists MorPOS domains for iframe embedding:

• Production: https://sale-gateway.morpara.com
• Sandbox: https://finagopay-pf-sale-api-gateway.prp.morpara.com

No additional CSP configuration is required.

💳 Test Cards

Test Cards (Sandbox Mode Only):

Refer to MorPOS Documentation for test card numbers and sandbox testing guidelines.

Testing Checklist:

• ✅ Successful payment flow
• ✅ Failed payment handling
• ✅ Network error scenarios
• ✅ Currency conversion (if applicable)
• ✅ Installment options
• ✅ Order status updates
• ✅ Guest checkout
• ✅ Registered customer checkout

🔍 Troubleshooting

Common Issues

Payment method not showing at checkout

Causes & Solutions:

1. Module Not Enabled

   • Check that the module is enabled: Stores → Configuration → Sales → Payment Methods
   • Verify "Enabled" is set to "Yes"

2. Currency Not Supported

   • Verify currency is supported (TRY, USD, EUR only)
   • Configure your store to use one of the supported currencies

3. Order Total Restrictions

   • Check minimum/maximum order total settings
   • Ensure order total falls within configured range

4. Country Restrictions

   • Verify country restrictions in configuration
   • Check customer's billing country is allowed

5. Cache Issues

   • Clear cache: php bin/magento cache:flush
   • Clear generated files: rm -rf generated/code/*

"Unable to initialize payment" error

Causes & Solutions:

1. Incorrect Credentials

   • Verify Merchant ID, Client ID, Client Secret, and API Key
   • Use Test Connection feature to validate

2. Environment Mismatch

   • Ensure Sandbox Mode setting matches your credentials (test vs production)

3. TLS Requirements

   • Server must support TLS 1.2 or higher
   • Check OpenSSL version: php -r "echo OPENSSL_VERSION_TEXT;"

4. cURL Issues

   • Verify cURL extension is installed: php -m | grep curl

Order not created after successful payment

Causes & Solutions:

1. Callback URL Issues

   • Check callback URL is accessible from internet
   • Verify server firewall allows incoming connections from MorPOS

2. Quote Expiration

   • Ensure quote has not expired during payment process

3. Server Errors

   • Review logs for callback processing errors
   • Check var/log/system.log for details

Connection Test Fails

1. Firewall/Network Issues

   # Test connectivity to MorPOS API
   curl -I https://sale-gateway.morpara.com
   

2. DNS Resolution

   # Verify DNS resolution
   nslookup sale-gateway.morpara.com
   

3. Server Time

   • Ensure server time is accurate (NTP recommended)

Logging

The module logs to Magento's standard logging system:

• File: var/log/system.log
• Level: Info for normal operations, Error for failures
• Content: No sensitive data is logged (security)

Enable Detailed Logging:

php bin/magento config:set dev/debug/debug_logging 1

Check Logs:

tail -f var/log/system.log | grep -i morpos

🌐 Internationalization

The module supports multiple languages:

• Turkish (tr_TR): Native support
• English (en_US): Default language

Adding New Translations

1. Create Language File:

   # Copy existing translation file
   cp app/code/MorPOS/PaymentGateway/i18n/en_US.csv \
      app/code/MorPOS/PaymentGateway/i18n/de_DE.csv
   

2. Translate Strings: Edit the CSV file and translate the strings

3. Deploy Static Content:

   php bin/magento setup:static-content:deploy de_DE
   php bin/magento cache:flush
   

📁 Developer Information

Module Structure

MorPOS/PaymentGateway/
├── Api/                    # API interfaces
├── Block/                  # UI blocks
├── Controller/             # Frontend controllers
├── Gateway/                # Payment gateway infrastructure
├── Helper/                 # Helper classes
├── Model/                  # Business logic and data models
├── Plugin/                 # Magento plugins
├── Setup/                  # Database installation scripts
├── etc/                    # Configuration files
├── i18n/                   # Translations
└── view/                   # Templates, layouts, static assets

Database Tables

Events

The module integrates with Magento's standard payment events and does not dispatch custom events.

API Endpoints

🤝 Contributing

We welcome contributions! Here's how to get started:

Development Setup

1. Fork the Repository

   git clone https://github.com/your-username/morpos-magento.git
   cd morpos-magento
   

2. Set Up Local Environment

   • Install Magento 2 locally
   • Link or copy module to app/code/MorPOS/PaymentGateway/
   • Enable developer mode: php bin/magento deploy:mode:set developer

3. Make Changes

   • Follow Magento coding standards
   • Add PHPDoc comments
   • Test thoroughly

4. Submit Pull Request

   • Create feature branch: git checkout -b feature/your-feature
   • Commit changes: git commit -m "Add your feature"
   • Push to branch: git push origin feature/your-feature
   • Open pull request on GitHub

Coding Standards

• Follow Magento Coding Standards
• Use PSR-4 autoloading for PHP classes
• Include PHPDoc comments for functions and classes
• Write meaningful commit messages

Testing Guidelines

Before submitting a pull request, test:

1. Installation/Uninstallation

   • Clean installation works
   • Uninstallation removes all data
   • Upgrade from previous version

2. Payment Flows

   • Successful payment (hosted & embedded)
   • Failed payment handling
   • Callback processing
   • Network errors

3. Multi-Currency

   • TRY, USD, EUR transactions
   • Currency display in admin and frontend

4. Compatibility

   • Magento 2.2, 2.3, 2.4
   • PHP 7.3, 7.4, 8.0, 8.1, 8.2

📄 License

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

🆘 Support

Documentation

• MorPOS Documentation: https://docs.morpara.com/
• MorPOS Dashboard: https://merchant.morpara.com/
• Magento Documentation: https://developer.adobe.com/commerce/

Issue Reporting

• GitHub Issues: Report a Bug
• Include:
  • Magento version
  • PHP version
  • Module version
  • Error messages / logs
  • Steps to reproduce

Commercial Support

• Morpara Support: Contact Support
• Email: support@morpara.com

Magento-Specific Issues

• Check Magento logs: var/log/system.log
• Run diagnostics: php bin/magento setup:di:compile
• Verify module status: php bin/magento module:status MorPOS_PaymentGateway

🙏 Acknowledgments

• Adobe/Magento Team - For the excellent e-commerce platform
• Magento Community - For the robust ecosystem and support
• Morpara - For the secure payment infrastructure

🔐 Security

If you discover a security vulnerability, please email security@morpara.com instead of using the issue tracker. All security vulnerabilities will be promptly addressed.

Security Features

• ✅ TLS 1.2+ encrypted communication
• ✅ Signed API requests with HMAC-SHA256
• ✅ Encrypted credential storage
• ✅ Conversation ID tracking
• ✅ Content Security Policy (CSP) compliance
• ✅ SQL injection prevention (Magento ORM)
• ✅ XSS protection (output escaping)
• ✅ CSRF protection (Magento form keys)
• ✅ No sensitive data logging

📝 Changelog

Version 1.0.0

• Initial release
• Hosted payment page support
• Embedded payment form support
• Multi-currency support (TRY, USD, EUR)
• Sandbox mode
• Multi-store configuration
• Guest checkout support
• Turkish and English translations

Made with ❤️ by Morpara

For more information about MorPOS payment solutions, visit morpara.com or check the documentation.