Создание модуля оплаты PrestaShop с ограничением по странам

Иногда интернет-магазину нужно показывать определённый способ оплаты не всем покупателям, а только клиентам из выбранных стран. Например, банковский перевод может быть удобен для одной группы стран, но нежелателен для другой. В такой ситуации можно создать отдельный модуль оплаты PrestaShop, похожий на стандартный банковский перевод, но с дополнительной проверкой страны покупателя по IP-адресу.

Эта статья рассчитана на администратора магазина с базовыми знаниями PrestaShop: установка модулей, работа с файлами сайта, FTP/SFTP, SSH, очистка кэша и базовое понимание структуры магазина. Мы не будем углубляться в сложную архитектуру ядра, но разберём, из чего состоит такой модуль, что нужно подготовить на сервере и какие проверки выполнить перед запуском на боевом сайте.

Что должен делать такой модуль

Задача модуля достаточно простая: добавить в checkout PrestaShop новый способ оплаты, который работает по логике банковского перевода, но отображается только для покупателей из разрешённых стран.

В практическом виде модуль должен выполнять следующие действия:

• добавить новый способ оплаты в оформление заказа;
• показать покупателю название способа оплаты, например Bank transfer или Payment by bank wire;
• проверить страну покупателя по IP-адресу;
• сравнить страну с разрешённым списком;
• если страна разрешена — показать способ оплаты;
• если страна не разрешена — скрыть способ оплаты;
• после подтверждения создать заказ в PrestaShop;
• назначить заказу статус ожидания банковского перевода;
• показать покупателю банковские реквизиты;
• отправить стандартное письмо с информацией о заказе.

Почему лучше сделать отдельный модуль, а не править стандартный Bank Wire

На первый взгляд может показаться, что проще изменить стандартный модуль банковского перевода. Но для рабочего магазина это плохой путь.

Стандартный модуль может быть перезаписан при обновлении PrestaShop или при обновлении самого модуля. Кроме того, если в магазине уже используется обычный банковский перевод, правка стандартного модуля может нарушить текущую схему оплаты, старые заказы, письма и настройки.

Гораздо безопаснее создать отдельный модуль, например:

sollerwiregeo

Такой модуль можно включать, отключать, удалять, переносить на другой магазин и дорабатывать независимо от стандартного банковского перевода.

Из чего состоит модуль PrestaShop

Обычные модули PrestaShop находятся в папке:

/modules/

Например, для нашего модуля структура может быть такой:

/modules/sollerwiregeo/

Главный файл модуля обычно имеет такое же имя, как и папка:

/modules/sollerwiregeo/sollerwiregeo.php

Минимальная рабочая структура платёжного модуля может выглядеть так:

sollerwiregeo/
├── sollerwiregeo.php
├── config.xml
├── index.php
├── logo.png
├── composer.json
├── vendor/
├── controllers/
│   └── front/
│       ├── payment.php
│       └── validation.php
├── views/
│   └── templates/
│       └── hook/
│           └── payment_options.tpl
└── mails/
    ├── en/
    ├── lv/
    └── ru/

Не все файлы обязательны на первом этапе, но для нормального платёжного модуля обычно нужны:

• основной PHP-файл модуля;
• front-контроллер для подтверждения оплаты;
• шаблон отображения оплаты в checkout;
• шаблон страницы подтверждения заказа;
• почтовые шаблоны;
• файл composer.json, если используются внешние PHP-библиотеки;
• папка vendor/ с установленными зависимостями.

Что нужно установить на сервер

Для такого модуля сервер должен поддерживать обычную работу PrestaShop и дополнительно иметь возможность читать GeoIP-базу. Ниже — практический список того, что нужно проверить перед разработкой или установкой.

1. Рабочая PrestaShop

Сначала нужна установленная и рабочая PrestaShop. Лучше не разрабатывать модуль сразу на боевом магазине. Правильная схема:

production shop  →  test / staging copy

На тестовой копии можно безопасно проверять установку, удаление, ошибки checkout, создание заказов и отправку писем.

Для PrestaShop 1.7.8 часто используется связка:

PHP 7.4
MariaDB / MySQL
Apache или Nginx + Apache
доступ по SSH
доступ к файлам сайта
включённый debug mode на тестовом сайте

2. PHP-расширения

Обычно для PrestaShop уже установлены основные PHP-расширения:

php-cli
php-curl
php-zip
php-intl
php-mbstring
php-xml
php-gd
php-mysql

Для работы с GeoIP не обязательно устанавливать отдельное системное расширение GeoIP. Удобнее использовать PHP-библиотеку MaxMind GeoIP2 через Composer. В этом случае PHP читает файл базы .mmdb через библиотеку.

3. Composer

Composer нужен для установки внешних PHP-библиотек. В нашем случае он используется для установки библиотеки GeoIP2.

Проверить Composer можно командой:

composer --version

Если Composer не установлен на Debian или Ubuntu, его можно установить так:

apt update
apt install composer -y

В папке модуля создаётся файл:

composer.json

Пример содержимого:

{
  "require": {
    "geoip2/geoip2": "^2.13"
  }
}

Затем в папке модуля выполняется установка зависимостей:

cd /path/to/prestashop/modules/sollerwiregeo
composer install --no-dev

После этого появится папка:

vendor/

Эту папку нужно оставить внутри модуля, потому что именно там находятся классы для чтения GeoIP-базы.

4. Логи и SSH-доступ

Для нормальной отладки желательно иметь доступ к серверу по SSH и возможность читать логи:

/var/log/apache2/
/var/log/nginx/
/var/log/php*/
/path/to/prestashop/var/logs/

Если сайт работает на shared-хостинге без SSH, модуль всё равно можно использовать, но папку vendor/ лучше подготовить заранее на локальном компьютере или тестовом сервере, а затем загрузить готовый модуль архивом.

Подготовка GeoIP-базы

Для определения страны покупателя по IP достаточно базы GeoLite2 Country. Она позволяет получить ISO-код страны, например:

LV
LT
EE
SE
FI
DE

Файл базы обычно называется:

GeoLite2-Country.mmdb

Лучше хранить его не в публичной папке сайта, а выше public_html, например:

/home/shop/private/geoip/GeoLite2-Country.mmdb

Пример структуры:

/home/shop/
├── private/
│   └── geoip/
│       └── GeoLite2-Country.mmdb
└── public_html/
    └── modules/
        └── sollerwiregeo/

Такой подход безопаснее, потому что база не будет доступна напрямую из браузера.

Пример подготовки папки:

mkdir -p /home/shop/private/geoip
chown -R shop:shop /home/shop/private/geoip
chmod 750 /home/shop/private/geoip
chmod 640 /home/shop/private/geoip/GeoLite2-Country.mmdb

В коде модуля путь к базе можно указать так:

const GEOIP_DB_PATH = _PS_ROOT_DIR_ . '/../private/geoip/GeoLite2-Country.mmdb';

Здесь _PS_ROOT_DIR_ — это корневая папка PrestaShop, обычно public_html. Поэтому ../private/geoip/ означает папку выше публичного каталога.

Основная логика работы модуля

Модуль должен не просто показывать кнопку оплаты, а аккуратно проходить несколько проверок. Если что-то не так, лучше скрыть способ оплаты, чем сломать весь checkout.

Проверка 1: активен ли модуль

Если модуль отключён в админке PrestaShop, он не должен отображаться в checkout.

Проверка 2: существует ли GeoIP-база

Если файл базы отсутствует или недоступен для чтения, модуль не должен вызывать фатальную ошибку.

if (!is_file(self::GEOIP_DB_PATH) || !is_readable(self::GEOIP_DB_PATH)) {
    return false;
}

Проверка 3: определить IP покупателя

В простом случае IP можно получить из стандартной переменной сервера:

$_SERVER['REMOTE_ADDR']

Но если сайт работает через Cloudflare, reverse proxy или другой CDN, нужно отдельно учитывать доверенные заголовки. Иначе модуль может видеть не IP покупателя, а IP прокси-сервера.

Проверка 4: определить страну

После подключения Composer autoload можно использовать библиотеку GeoIP2:

require_once __DIR__ . '/vendor/autoload.php';

$reader = new \GeoIp2\Database\Reader(self::GEOIP_DB_PATH);
$record = $reader->country($ip);
$countryIso = $record->country->isoCode;

В результате модуль получает ISO-код страны, например:

LV

Проверка 5: сравнить со списком разрешённых стран

В настройках модуля можно хранить список стран:

LV,LT,EE,SE,FI

Если страна покупателя входит в этот список, способ оплаты показывается. Если нет — скрывается.

Как модуль создаёт заказ

Платёжный модуль PrestaShop не просто выводит кнопку в checkout. Он должен корректно создать заказ в системе.

Обычно такой модуль наследуется от класса:

PaymentModule

После подтверждения оплаты вызывается метод создания заказа:

$this->module->validateOrder(...);

Для банковского перевода заказ обычно получает статус ожидания оплаты, например:

Awaiting bank wire payment

Или модуль может создать собственный статус, например:

Awaiting geo bank transfer payment

Для администратора магазина важно понимать: такой модуль не списывает деньги автоматически. Он только создаёт заказ и сообщает покупателю реквизиты для оплаты. Фактическое поступление денег проверяется вручную по банковскому счёту.

Что должно быть в настройках модуля

Чтобы администратор мог управлять модулем без правки PHP-кода, нужно сделать страницу настроек в Back Office.

Минимальный набор настроек:

• владелец банковского счёта;
• название банка;
• IBAN;
• SWIFT / BIC;
• инструкция для покупателя;
• список разрешённых стран;
• режим отладки.

Пример поля разрешённых стран:

LV,LT,EE,SE,FI

Также полезно добавить режим отладки:

Debug mode: Yes / No

В режиме отладки модуль может записывать техническую информацию:

IP: 85.xxx.xxx.xxx
Detected country: LV
Payment visible: yes

Где должен отображаться способ оплаты

В PrestaShop 1.7 способ оплаты отображается в checkout на этапе выбора оплаты.

Покупатель должен увидеть примерно такой вариант:

Pay by bank transfer
Your order will be processed after payment is received.

После выбора оплаты и подтверждения заказа покупатель попадает на страницу подтверждения, где видит банковские реквизиты:

Order confirmed

Please transfer the total amount to the following bank account:
IBAN: ...
SWIFT: ...
Bank: ...

Администратор магазина видит заказ в Back Office, а покупатель получает письмо с инструкциями по оплате.

Как установить готовый модуль

Когда модуль готов, его нужно упаковать в ZIP-архив.

Правильная структура архива:

sollerwiregeo.zip
└── sollerwiregeo/
    ├── sollerwiregeo.php
    ├── config.xml
    ├── vendor/
    ├── controllers/
    ├── views/
    └── mails/

Важно: внутри архива должна быть папка модуля, а не просто файлы без папки.

Установка через админку PrestaShop:

Back Office → Modules → Module Manager → Upload a module

После установки нужно:

1. открыть настройки модуля;
2. указать банковские реквизиты;
3. указать разрешённые страны;
4. сохранить настройки;
5. очистить кэш PrestaShop;
6. проверить checkout;
7. создать тестовый заказ.

Что проверить после установки

Минимальный чек-лист:

• модуль устанавливается без ошибки;
• модуль включается в Module Manager;
• настройки сохраняются;
• GeoIP-база читается;
• для разрешённой страны способ оплаты виден;
• для запрещённой страны способ оплаты скрыт;
• заказ создаётся;
• статус заказа правильный;
• покупатель видит банковские реквизиты;
• администратор видит заказ в Back Office;
• письмо покупателю отправляется;
• в логах нет PHP Fatal error.

Проверка синтаксиса основного файла:

php -l /path/to/prestashop/modules/sollerwiregeo/sollerwiregeo.php

Очистка кэша PrestaShop 1.7:

rm -rf /path/to/prestashop/var/cache/prod/*
rm -rf /path/to/prestashop/var/cache/dev/*

Частые ошибки

1. Модуль не появляется в списке оплат

Возможные причины:

• модуль не установлен;
• модуль отключён;
• не зарегистрирован нужный hook;
• страна покупателя не входит в разрешённый список;
• GeoIP-база отсутствует;
• есть ошибка в PHP-коде;
• кэш PrestaShop не очищен.

2. Ошибка Composer autoload

Если появляется ошибка, связанная с классами GeoIp2 или MaxMind, значит не установлены зависимости.

Проверить наличие autoload:

ls -la /path/to/prestashop/modules/sollerwiregeo/vendor/autoload.php

Если файла нет:

cd /path/to/prestashop/modules/sollerwiregeo
composer install --no-dev

3. GeoIP-база не читается

Проверить файл:

ls -lh /home/shop/private/geoip/GeoLite2-Country.mmdb

Проверить права по всему пути:

namei -l /home/shop/private/geoip/GeoLite2-Country.mmdb

PHP-пользователь должен иметь право читать файл базы.

4. Определяется неправильная страна

Такое бывает, если сайт работает через proxy, CDN или Cloudflare. В этом случае REMOTE_ADDR может быть IP-адресом промежуточного сервера, а не покупателя.

Возможные заголовки:

HTTP_CF_CONNECTING_IP
X-Forwarded-For

Но использовать их нужно только при правильной настройке доверенного proxy. Иначе злоумышленник может подставить произвольный IP в заголовок.

5. Заказ не создаётся после выбора оплаты

В этом случае нужно проверить:

• front-контроллер validation.php;
• вызов validateOrder();
• наличие активной корзины;
• наличие клиента;
• статус заказа;
• логи PrestaShop;
• логи PHP-FPM или Apache.

Безопасность и приватность

Модуль работает с IP-адресом покупателя, поэтому важно соблюдать несколько правил:

• не показывать IP покупателя на публичных страницах;
• не хранить лишние IP-логи без необходимости;
• не размещать GeoIP-базу в публичной папке сайта;
• не использовать GeoIP как единственный юридический критерий для спорных ограничений;
• оставить покупателю альтернативный способ оплаты;
• учитывать, что при VPN страна может определиться неправильно.

Рекомендуемая рабочая схема разработки

Безопасная схема для администратора магазина выглядит так:

1. Сделать копию магазина на тестовом домене.
2. Создать папку модуля в /modules/.
3. Установить Composer-зависимости.
4. Подключить GeoLite2 Country database.
5. Реализовать базовый платёжный модуль.
6. Добавить настройки банковских реквизитов.
7. Добавить список разрешённых стран.
8. Проверить отображение в checkout.
9. Проверить создание заказа.
10. Проверить письма.
11. Упаковать модуль в ZIP.
12. Установить на боевой магазин.
13. Очистить кэш.
14. Сделать тестовый заказ.

Перед любыми изменениями на боевом сайте желательно сделать резервную копию:

cp -a /path/to/prestashop/modules/sollerwiregeo \
/path/to/prestashop/modules/sollerwiregeo.bak.$(date +%F-%H%M%S)

Что должен понимать администратор магазина

Для работы с таким модулем не обязательно быть профессиональным разработчиком, но нужно понимать базовые вещи:

• что такое папка modules;
• как загрузить ZIP-модуль в PrestaShop;
• как очистить кэш;
• как проверить PHP-ошибки;
• как работать по SSH;
• как проверить права на файл;
• как отличить тестовый сайт от боевого;
• как сделать резервную копию перед изменениями.

Если магазин работает на VPS, администратору желательно иметь доступ к:

• SSH;
• PHP CLI;
• Composer;
• логам PHP, Apache или Nginx;
• файлам сайта.

Заключение

Модуль оплаты с ограничением по стране покупателя — это практичное решение для магазинов, которым нужно гибко управлять доступными способами оплаты. Его можно сделать на базе логики стандартного банковского перевода, но лучше оформить как отдельный независимый модуль.

Главные элементы такого решения:

• отдельный payment module;
• наследование от PaymentModule;
• создание заказа через validateOrder();
• настройки банковских реквизитов;
• список разрешённых стран;
• GeoLite2 Country database;
• библиотека MaxMind GeoIP2;
• безопасное хранение базы вне public_html;
• тестирование на staging-копии магазина.

Такой подход позволяет не ломать стандартный банковский перевод, не вмешиваться в ядро PrestaShop и сохранить возможность обновлять магазин в будущем.

🧩 Нужен модуль оплаты для PrestaShop?

SOLLER.LV помогает создавать и дорабатывать модули PrestaShop: способы оплаты, интеграции доставки, импорт товаров, GeoIP-ограничения, checkout-логику и автоматизацию e-commerce процессов.