README

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

Log into Magento Admin
Navigate to Stores → Configuration → Sales → Payment Methods
Locate EchoPay section
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:

Create Magento Marketplace account
Register module with correct package structure
Provide Security Scan Tool clearance
Submit for approval

Direct Distribution

For direct delivery:

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

Packagist (Composer)

To publish on Packagist:

Push code to GitHub
Register repo at packagist.org
Tag releases with version numbers
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

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

Customer adds items to cart and proceeds to checkout
Selects EchoPay as payment method
Clicks "Pay Now" button (button disables to prevent double-clicks)
Payment link created via EchoPay API
Customer redirected to EchoPay payment page
Completes payment with their bank
Returns to store with payment status
Order is created automatically on success
Cart is cleared
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

Get your API Key:
- Login to EchoPay dashboard
- Go to Settings → API
- Create a new API key and copy it
Set Webhook Secret:
- In EchoPay dashboard → Settings → Notifications
- Copy your webhook secret
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

Enable the module:

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

Run compilation:

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

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

Add products to cart
Proceed to checkout
Select "EchoPay" as payment method
Click "Pay Now"
Verify button disables and shows "Processing..."
Complete payment with mock bank
Verify redirect to success page
Check that order was created in Magento
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.

echopay / module-payment

Maintainers

Package info

Statistics

Security

README

Features

Requirements

Installation via Composer

Installation Manual (Docker)

Configuration

Enable/Disable Management

Enable Module

Disable Module

Check Module Status

Uninstall/Remove

Via Composer

Manual Removal

Module Structure

Troubleshooting

Admin Panel Issues

Payment Method Not Showing

Database Issues After Update

Versioning

Distribution Channels

Magento Marketplace

Direct Distribution

Packagist (Composer)

CI/CD Pipeline

Support

License

Changelog

1.0.0 (2026-02-07)

Payment Flow

Configuration

API Endpoints

API Configuration

Development

Module Structure Details

Key Components

Installation & Setup

Payment Statuses

Testing

Development Environment

Testing Payment Flow

Troubleshooting

Docker Commands (Development)

API Reference

Module Dependencies

Support