README

Packagist

Direct bank transfer payment gateway integration for Magento 2.

• Module Name: Echopay_Payment
• Type: magento2-module
• Version: 1.0.1
• Package: echopay/module-payment

Features

• Easy-to-integrate bank transfer payment method
• Secure webhook processing for payment confirmations
• Configurable payment options in admin
• Real-time payment status tracking
• Multi-currency support
• Admin panel with jQuery compatibility fixes

Requirements

• Magento 2.3+ (tested on 2.4.x)
• PHP 7.4+
• Composer
• cURL extension

Installation via Composer

composer require echopay/module-payment:^1.0
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy
php bin/magento cache:flush

Installation Manual (Docker)

If you're using the included Docker setup:

docker-compose up -d
bash ./bash/cli.sh
# Select option 1: Start Environment

Configuration

1. Log into Magento Admin
2. Navigate to Stores → Configuration → Sales → Payment Methods
3. Locate EchoPay section
4. Configure:
   • Enabled: Enable/disable payment method
   • Title: Display name on checkout
   • API Key: Your EchoPay API credentials
   • API Secret: Your EchoPay secret key
   • Environment: Live or Testing mode

Enable/Disable Management

Enable Module

php bin/magento module:enable Echopay_Payment
php bin/magento setup:upgrade
php bin/magento setup:static-content:deploy

Disable Module

php bin/magento module:disable Echopay_Payment
php bin/magento setup:upgrade

Check Module Status

php bin/magento module:status | grep Echopay

Uninstall/Remove

Via Composer

composer remove echopay/module-payment
php bin/magento setup:upgrade

Manual Removal

rm -rf app/code/Echopay/Payment
php bin/magento setup:upgrade
php bin/magento cache:flush

Module Structure

Echopay/Payment/
├── Block/              # Admin and frontend blocks
├── Controller/         # Request handlers
├── Model/              # Business logic and data models
├── Observer/           # Event observers
├── etc/                # Configuration
│   ├── module.xml      # Module declaration
│   ├── config.xml      # System configuration
│   ├── adminhtml/      # Admin configuration
│   └── frontend/       # Frontend configuration
├── view/               # Templates and layouts
│   ├── frontend/       # Checkout and customer pages
│   └── adminhtml/      # Admin pages and configurations
├── Api/                # API interfaces (if applicable)
├── composer.json       # Package metadata
├── registration.php    # Module registration
└── README.md           # This file

Troubleshooting

Admin Panel Issues

Problem: Accordion sections not opening in admin

• Solution: Clear cache php bin/magento cache:flush
• The module includes jQuery/Prototype.js compatibility fixes automatically

Problem: Configuration form won't save

• Solution: Check browser console for errors, clear var/cache

Payment Method Not Showing

Problem: Payment method doesn't appear at checkout

• Verify: Module is enabled (php bin/magento module:status)
• Check: Payment method is configured in admin
• Clear: Browser cache (Cmd/Ctrl+Shift+R)

Database Issues After Update

php bin/magento setup:upgrade --keep-generated
php bin/magento cache:clean

Versioning

This module follows Semantic Versioning:

• MAJOR: Incompatible changes
• MINOR: Backward-compatible features
• PATCH: Bug fixes

Distribution Channels

Magento Marketplace

To publish on Magento Marketplace:

1. Create Magento Marketplace account
2. Register module with correct package structure
3. Provide Security Scan Tool clearance
4. Submit for approval

Direct Distribution

For direct delivery:

1. Package: tar czf echopay-module-payment-1.0.0.tar.gz app/code/Echopay/
2. Document: Installation steps and dependencies
3. Support: Provide contact and documentation links

Packagist (Composer)

To publish on Packagist:

1. Push code to GitHub
2. Register repo at packagist.org
3. Tag releases with version numbers
4. Composer will auto-detect new versions

CI/CD Pipeline

For automated testing and releases:

# Example GitHub Actions
- Test on Magento 2.3, 2.4, 2.4.1
- PHP CodeSniffer for code standards
- Unit tests
- Integration tests
- Auto-tag and release on merge

Support

• Email: support@echopay.com
• Documentation: https://docs.echopay.com/magento2
• GitHub Issues: https://github.com/echopay/magento2-payment-module

License

Proprietary - All rights reserved. See LICENSE file.

Changelog

1.0.0 (2026-02-07)

• ✨ Initial release
• ✨ Core payment integration
• ✨ Admin configuration interface
• ✨ Webhook processing
• 🐛 jQuery compatibility fixes for legacy admin

Last Updated: 2026-02-07
Maintained By: EchoPay Team The EchoPay Payment module provides:

• ✅ Payment Link Integration - Seamless EchoPay open banking payment processing
• ✅ Checkout Integration - "Pay Now" button with double-click protection
• ✅ Order Creation - Automatic order creation on successful payment
• ✅ Cart Management - Cart cleared after successful payment
• ✅ Payment Status Handling - Support for SUCCESS, PROCESSING, INITIATED, FAILED, and PENDING statuses
• ✅ Callback Processing - Handles payment callbacks with automatic order updates
• ✅ Admin Configuration - Easy setup via Magento admin panel
• ✅ Multiple Environments - Support for development and production modes

Payment Flow

1. Customer adds items to cart and proceeds to checkout
2. Selects EchoPay as payment method
3. Clicks "Pay Now" button (button disables to prevent double-clicks)
4. Payment link created via EchoPay API
5. Customer redirected to EchoPay payment page
6. Completes payment with their bank
7. Returns to store with payment status
8. Order is created automatically on success
9. Cart is cleared
10. Customer sees success message with order confirmation

Configuration

Payment method settings can be configured in the Magento Admin:

Location: Stores > Settings > Configuration > Sales > Payment Methods > EchoPay

Required settings:

• Enable EchoPay: Enable/disable the payment method
• Environment: Select dev for testing or prod for production
• API Key: Your EchoPay API key (from EchoPay dashboard)
• Webhook Secret: Your webhook signing secret for callback verification
• Custom Callback URL: Set in EchoPay dashboard to http://your-domain.com/echopay/payment/callback

API Endpoints

• Create Payment Link: POST /echopay/payment/create

  • Creates a payment link for the current quote
  • Returns: { success: boolean, paymentLink: { id, url, date } }

• Payment Callback: GET /echopay/payment/callback?status={status}&id={link_id}&info={info}

  • Receives payment status from EchoPay
  • Creates order on success
  • Redirects to appropriate page

API Configuration

1. Get your API Key:

   • Login to EchoPay dashboard
   • Go to Settings → API
   • Create a new API key and copy it

2. Set Webhook Secret:

   • In EchoPay dashboard → Settings → Notifications
   • Copy your webhook secret

3. Configure Callback URL:

   • In EchoPay dashboard → Settings → API
   • Set Custom Callback to: http://your-store.com/echopay/payment/callback

Development

Module Structure Details

Echopay/Payment/
├── Model/
│   ├── Payment/
│   │   └── Echopay.php              # Payment method model
│   └── PaymentMethod.php            # Payment method configuration
├── Controller/
│   └── Payment/
│       ├── Create.php               # AJAX endpoint for payment link creation
│       └── Callback.php             # Payment callback handler
├── Service/
│   └── EchopayApiService.php        # EchoPay API service (token, links, verification)
├── view/frontend/
│   ├── js/
│   │   └── view/payment/method-renderer/
│   │       └── echopay-method.js   # Frontend payment handler with button state
│   └── templates/payment/
│       └── echopay.html            # Payment method template
└── etc/
    ├── module.xml
    ├── di.xml
    ├── config.xml
    ├── frontend/routes.xml
    └── adminhtml/system.xml

Key Components

EchopayApiService

• Handles OAuth token generation with 1-hour expiry and 5-minute buffer
• Creates and retrieves payment links
• Verifies webhook signatures using HMAC SHA256
• Manages API authentication and error handling

Payment Method (Echopay.php)

• Extends Magento\Payment\Model\Method\AbstractMethod
• Integrates with Magento payment gateway
• Handles payment capture flow
• Configured to support partial captures but no refunds/voids

Create Controller

• Receives "Pay Now" button clicks via AJAX
• Extracts cart and customer data
• Creates payment link via EchoPay API
• Returns link ID and redirect URL for frontend

Callback Controller

• Handles redirects from EchoPay after payment completion
• Fetches payment status from EchoPay API
• Creates order automatically on SUCCESS or INITIATED status
• Deactivates quote and clears cart
• Manages customer session and redirects to appropriate page

Frontend Renderer (echopay-method.js)

• Handles "Pay Now" button interactions
• Disables button and shows "Processing..." during payment
• Sends AJAX request to create payment link
• Redirects to EchoPay payment page
• Handles errors with appropriate messaging and button re-enable

Installation & Setup

1. Enable the module:

   docker exec magento2-web php bin/magento module:enable Echopay_Payment
   docker exec magento2-web php bin/magento setup:upgrade

2. Run compilation:

   docker exec magento2-web php bin/magento setup:di:compile
   docker exec magento2-web php bin/magento setup:static-content:deploy -f

3. Configure in Admin:

   • Navigate to Stores → Configuration → Sales → Payment Methods
   • Find "EchoPay" section
   • Enable the method
   • Enter your API Key and select environment
   • Add your webhook secret
   • Enter your callback URL

Payment Statuses

The module handles the following payment statuses from EchoPay:

• SUCCESS: Payment completed successfully → Order created, customer redirected to success page
• INITIATED: Payment link created → Order created, customer redirected to success page
• PROCESSING: Payment is being processed → Message shown, customer can view cart
• FAILED: Payment failed → Quote restored, customer can retry
• PENDING: Payment pending → Quote restored, customer can retry

Testing

Development Environment

• Use EchoPay development API: https://dev.cloud.echopay.co.uk/v2
• Use test API Key: Zd77rh7uLg5lvMKdn1yj
• Use mock bank account login during payment

Testing Payment Flow

1. Add products to cart
2. Proceed to checkout
3. Select "EchoPay" as payment method
4. Click "Pay Now"
5. Verify button disables and shows "Processing..."
6. Complete payment with mock bank
7. Verify redirect to success page
8. Check that order was created in Magento
9. Verify cart is empty

Troubleshooting

Payment link creation fails

• Check API Key in admin configuration
• Verify environment is set correctly (dev vs prod)
• Check quote has items and customer data
• Review error logs in var/log/system.log

Callback not being called

• Verify callback URL in EchoPay dashboard matches your store
• Check firewall isn't blocking EchoPay servers
• Review Magento logs for any errors
• Verify webhook secret is configured

Order not created after payment

• Check DI compilation: docker exec magento2-web php bin/magento setup:di:compile
• Verify cache is cleared: docker exec magento2-web php bin/magento cache:clean
• Review order creation permissions
• Check database for quote changes

Button stays disabled

• Check browser console for JavaScript errors
• Verify static content deployed: docker exec magento2-web php bin/magento setup:static-content:deploy -f
• Check CSRF token is valid
• Clear browser cache

Docker Commands (Development)

If running in Docker:

# Recompile DI
docker exec magento2-web php bin/magento setup:di:compile

# Deploy static content
docker exec magento2-web php bin/magento setup:static-content:deploy -f

# Clear cache
docker exec magento2-web php bin/magento cache:clean

# Disable module
docker exec magento2-web php bin/magento module:disable Echopay_Payment
docker exec magento2-web php bin/magento setup:upgrade

# Check logs
docker exec magento2-web tail -f var/log/system.log

API Reference

EchoPay API Base URLs

• Development: https://dev.cloud.echopay.co.uk/v2
• Production: https://api.echopay.co.uk/v2

Create Payment Link

POST {base_url}/payment-links
Authorization: Bearer {token}
Content-Type: application/json

{
  "amount": 1000,
  "currency": "GBP",
  "description": "Order #100001",
  "redirectUrl": "https://store.com/echopay/payment/callback"
}

Get Payment Link Status

GET {base_url}/payment-links/{link_id}
Authorization: Bearer {token}

Get Token

POST {base_url}/token
Authorization: Basic base64(api_key:)

Module Dependencies

• PHP: >= 8.0
• Magento: 2.x
• composer package: echopay/module-payment

Support

For issues or questions about this module, please contact the EchoPay development team.