PrestaShop maksājumu moduļa izveide ar valstu ierobežojumu

Dažkārt interneta veikalam ir nepieciešams rādīt konkrētu maksājuma veidu ne visiem pircējiem, bet tikai klientiem no noteiktām valstīm. Piemēram, bankas pārskaitījums var būt ērts vienai valstu grupai, bet nevēlams citai. Šādā gadījumā var izveidot atsevišķu PrestaShop maksājumu moduli, kas darbojas līdzīgi standarta bankas pārskaitījumam, bet papildus pārbauda pircēja valsti pēc IP adreses.

Šis raksts ir paredzēts veikala administratoram ar pamata zināšanām par PrestaShop: moduļu uzstādīšanu, darbu ar vietnes failiem, FTP/SFTP, SSH, kešatmiņas dzēšanu un pamatizpratni par veikala struktūru. Mēs neiesim dziļi PrestaShop kodola arhitektūrā, bet apskatīsim, no kā sastāv šāds modulis, kas jāsagatavo serverī un kādas pārbaudes jāveic pirms palaišanas dzīvajā veikalā.

Kas šādam modulim jādara

Moduļa uzdevums ir samērā vienkāršs: pievienot PrestaShop checkout sadaļai jaunu maksājuma veidu, kas darbojas pēc bankas pārskaitījuma principa, bet tiek rādīts tikai pircējiem no atļautajām valstīm.

Praktiski modulim jāveic šādas darbības:

• jāpievieno jauns maksājuma veids pasūtījuma noformēšanā;
• pircējam jāparāda maksājuma nosaukums, piemēram, Bank transfer vai Payment by bank wire;
• jāpārbauda pircēja valsts pēc IP adreses;
• jāsalīdzina valsts ar atļauto valstu sarakstu;
• ja valsts ir atļauta — maksājuma veids jāparāda;
• ja valsts nav atļauta — maksājuma veids jāpaslēpj;
• pēc apstiprināšanas jāizveido pasūtījums PrestaShop sistēmā;
• pasūtījumam jāpiešķir statuss, kas norāda uz bankas pārskaitījuma gaidīšanu;
• pircējam jāparāda bankas rekvizīti;
• jānosūta standarta e-pasts ar pasūtījuma informāciju.

Kāpēc labāk izveidot atsevišķu moduli, nevis labot standarta Bank Wire

Pirmajā brīdī var šķist, ka vienkāršāk ir izmainīt standarta bankas pārskaitījuma moduli. Tomēr darba veikalam tas nav drošākais risinājums.

Standarta modulis var tikt pārrakstīts PrestaShop vai paša moduļa atjaunināšanas laikā. Turklāt, ja veikalā jau tiek izmantots parastais bankas pārskaitījums, standarta moduļa labošana var sabojāt esošo maksājumu shēmu, vecos pasūtījumus, e-pastus un iestatījumus.

Daudz drošāk ir izveidot atsevišķu moduli, piemēram:

sollerwiregeo

Šādu moduli var ieslēgt, izslēgt, dzēst, pārvietot uz citu veikalu un pilnveidot neatkarīgi no standarta bankas pārskaitījuma moduļa.

No kā sastāv PrestaShop modulis

Parasti PrestaShop moduļi atrodas mapē:

/modules/

Piemēram, mūsu modulim struktūra varētu būt šāda:

/modules/sollerwiregeo/

Galvenajam moduļa failam parasti ir tāds pats nosaukums kā moduļa mapei:

/modules/sollerwiregeo/sollerwiregeo.php

Minimāla maksājumu moduļa struktūra var izskatīties šādi:

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/

Ne visi faili ir obligāti jau pirmajā etapā, bet normālam maksājumu modulim parasti ir nepieciešami:

• galvenais moduļa PHP fails;
• front-kontrolieris maksājuma apstiprināšanai;
• checkout maksājuma attēlošanas veidne;
• pasūtījuma apstiprinājuma lapas veidne;
• e-pastu veidnes;
• composer.json fails, ja tiek izmantotas ārējas PHP bibliotēkas;
• vendor/ mape ar uzstādītajām atkarībām.

Kas jāuzstāda serverī

Šādam modulim serverim jāspēj normāli darbināt PrestaShop un papildus nolasīt GeoIP datubāzi. Zemāk ir praktisks saraksts ar lietām, kas jāpārbauda pirms izstrādes vai uzstādīšanas.

1. Darbojošs PrestaShop veikals

Vispirms ir nepieciešams uzstādīts un strādājošs PrestaShop veikals. Moduli labāk neizstrādāt uzreiz dzīvajā veikalā. Drošāka shēma:

production shop  →  test / staging copy

Testa kopijā var droši pārbaudīt uzstādīšanu, dzēšanu, checkout kļūdas, pasūtījumu izveidi un e-pastu nosūtīšanu.

PrestaShop 1.7.8 vidē bieži tiek izmantota šāda kombinācija:

PHP 7.4
MariaDB / MySQL
Apache vai Nginx + Apache
SSH piekļuve
piekļuve vietnes failiem
ieslēgts debug mode testa vietnē

2. PHP paplašinājumi

Parasti PrestaShop darbībai jau ir uzstādīti galvenie PHP paplašinājumi:

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

Darbam ar GeoIP nav obligāti jāuzstāda atsevišķs sistēmas GeoIP paplašinājums. Ērtāk ir izmantot MaxMind GeoIP2 PHP bibliotēku caur Composer. Šādā gadījumā PHP nolasa .mmdb datubāzes failu ar bibliotēkas palīdzību.

3. Composer

Composer ir nepieciešams ārējo PHP bibliotēku uzstādīšanai. Šajā gadījumā tas tiek izmantots GeoIP2 bibliotēkas uzstādīšanai.

Composer var pārbaudīt ar komandu:

composer --version

Ja Debian vai Ubuntu serverī Composer nav uzstādīts, to var uzstādīt šādi:

apt update
apt install composer -y

Moduļa mapē tiek izveidots fails:

composer.json

Piemērs:

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

Pēc tam moduļa mapē tiek palaista atkarību uzstādīšana:

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

Pēc tam parādīsies mape:

vendor/

Šī mape jāatstāj modulī, jo tieši tajā atrodas klases GeoIP datubāzes nolasīšanai.

4. Žurnāli un SSH piekļuve

Normālai atkļūdošanai vēlams nodrošināt SSH piekļuvi serverim un iespēju lasīt žurnālus:

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

Ja vietne darbojas uz shared hosting bez SSH piekļuves, moduli joprojām var izmantot, bet vendor/ mapi labāk sagatavot iepriekš lokālajā datorā vai testa serverī un pēc tam augšupielādēt jau gatavu moduļa arhīvu.

GeoIP datubāzes sagatavošana

Lai noteiktu pircēja valsti pēc IP adreses, pietiek ar GeoLite2 Country datubāzi. Tā ļauj iegūt valsts ISO kodu, piemēram:

LV
LT
EE
SE
FI
DE

Datubāzes fails parasti saucas:

GeoLite2-Country.mmdb

To labāk glabāt nevis publiskajā vietnes mapē, bet vienu līmeni virs public_html, piemēram:

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

Struktūras piemērs:

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

Šāda pieeja ir drošāka, jo datubāze nebūs tieši pieejama no pārlūka.

Mapes sagatavošanas piemērs:

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

Moduļa kodā ceļu uz datubāzi var norādīt šādi:

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

Šeit _PS_ROOT_DIR_ ir PrestaShop saknes mape, parasti public_html. Tāpēc ../private/geoip/ nozīmē mapi virs publiskā kataloga.

Galvenā moduļa darbības loģika

Modulim nav vienkārši jāparāda maksājuma poga. Tam korekti jāiziet vairākas pārbaudes. Ja kaut kas nav kārtībā, labāk maksājuma veidu paslēpt, nevis salauzt visu checkout procesu.

Pārbaude 1: vai modulis ir aktīvs

Ja modulis ir izslēgts PrestaShop administrācijas panelī, tam nav jāparādās checkout sadaļā.

Pārbaude 2: vai GeoIP datubāze eksistē

Ja datubāzes fails neeksistē vai nav nolasāms, modulim nevajadzētu izraisīt fatālu kļūdu.

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

Pārbaude 3: noteikt pircēja IP adresi

Vienkāršā gadījumā IP adresi var iegūt no standarta servera mainīgā:

$_SERVER['REMOTE_ADDR']

Taču, ja vietne darbojas caur Cloudflare, reverse proxy vai citu CDN, atsevišķi jāņem vērā uzticamie galvenes lauki. Pretējā gadījumā modulis var redzēt nevis pircēja IP adresi, bet proxy servera IP adresi.

Pārbaude 4: noteikt valsti

Pēc Composer autoload pieslēgšanas var izmantot GeoIP2 bibliotēku:

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

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

Rezultātā modulis iegūst valsts ISO kodu, piemēram:

LV

Pārbaude 5: salīdzināt ar atļauto valstu sarakstu

Moduļa iestatījumos var glabāt valstu sarakstu:

LV,LT,EE,SE,FI

Ja pircēja valsts ir šajā sarakstā, maksājuma veids tiek parādīts. Ja nav — tas tiek paslēpts.

Kā modulis izveido pasūtījumu

PrestaShop maksājumu modulis ne tikai parāda pogu checkout sadaļā. Tam ir korekti jāizveido pasūtījums sistēmā.

Parasti šāds modulis manto klasi:

PaymentModule

Pēc maksājuma apstiprināšanas tiek izsaukta pasūtījuma izveides metode:

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

Bankas pārskaitījumam pasūtījums parasti saņem statusu, kas nozīmē maksājuma gaidīšanu, piemēram:

Awaiting bank wire payment

Vai arī modulis var izveidot savu statusu, piemēram:

Awaiting geo bank transfer payment

Veikala administratoram ir svarīgi saprast: šāds modulis automātiski nenoņem naudu no pircēja kartes vai konta. Tas tikai izveido pasūtījumu un parāda pircējam bankas rekvizītus. Faktiskais maksājuma saņemšanas fakts tiek pārbaudīts manuāli bankas kontā.

Kam jābūt moduļa iestatījumos

Lai administrators varētu pārvaldīt moduli bez PHP koda labošanas, ir vēlams izveidot iestatījumu lapu Back Office sadaļā.

Minimālais iestatījumu komplekts:

• bankas konta īpašnieks;
• bankas nosaukums;
• IBAN;
• SWIFT / BIC;
• instrukcija pircējam;
• atļauto valstu saraksts;
• atkļūdošanas režīms.

Atļauto valstu lauka piemērs:

LV,LT,EE,SE,FI

Noderīgi ir pievienot arī atkļūdošanas režīmu:

Debug mode: Yes / No

Atkļūdošanas režīmā modulis var pierakstīt tehnisko informāciju:

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

Kur jāparādās maksājuma veidam

PrestaShop 1.7 maksājuma veids tiek parādīts checkout procesā maksājuma izvēles solī.

Pircējam vajadzētu redzēt aptuveni šādu variantu:

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

Pēc maksājuma veida izvēles un pasūtījuma apstiprināšanas pircējs nonāk apstiprinājuma lapā, kur redz bankas rekvizītus:

Order confirmed

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

Veikala administrators pasūtījumu redz Back Office sadaļā, bet pircējs saņem e-pastu ar maksājuma instrukciju.

Kā uzstādīt gatavu moduli

Kad modulis ir gatavs, tas jāiepako ZIP arhīvā.

Pareiza arhīva struktūra:

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

Svarīgi: arhīva iekšpusē jābūt moduļa mapei, nevis tikai failiem bez mapes.

Uzstādīšana caur PrestaShop administrācijas paneli:

Back Office → Modules → Module Manager → Upload a module

Pēc uzstādīšanas nepieciešams:

1. atvērt moduļa iestatījumus;
2. norādīt bankas rekvizītus;
3. norādīt atļautās valstis;
4. saglabāt iestatījumus;
5. notīrīt PrestaShop kešatmiņu;
6. pārbaudīt checkout procesu;
7. izveidot testa pasūtījumu.

Ko pārbaudīt pēc uzstādīšanas

Minimālais pārbaudes saraksts:

• modulis uzstādās bez kļūdām;
• moduli var ieslēgt Module Manager sadaļā;
• iestatījumi saglabājas;
• GeoIP datubāze ir nolasāma;
• pircējam no atļautas valsts maksājuma veids ir redzams;
• pircējam no neatļautas valsts maksājuma veids ir paslēpts;
• pasūtījums tiek izveidots;
• pasūtījuma statuss ir pareizs;
• pircējs redz bankas rekvizītus;
• administrators redz pasūtījumu Back Office sadaļā;
• pircējam tiek nosūtīts e-pasts;
• žurnālos nav PHP Fatal error kļūdu.

Galvenā faila sintakses pārbaude:

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

PrestaShop 1.7 kešatmiņas dzēšana:

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

Biežākās kļūdas

1. Modulis neparādās maksājumu sarakstā

Iespējamie iemesli:

• modulis nav uzstādīts;
• modulis ir izslēgts;
• nav reģistrēts vajadzīgais hook;
• pircēja valsts nav atļauto valstu sarakstā;
• GeoIP datubāze neeksistē;
• PHP kodā ir kļūda;
• PrestaShop kešatmiņa nav notīrīta.

2. Composer autoload kļūda

Ja parādās kļūda, kas saistīta ar GeoIp2 vai MaxMind klasēm, tas nozīmē, ka nav uzstādītas atkarības.

Pārbaudīt autoload failu:

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

Ja faila nav:

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

3. GeoIP datubāze nav nolasāma

Pārbaudīt failu:

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

Pārbaudīt tiesības visā ceļā:

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

PHP lietotājam jābūt tiesībām nolasīt datubāzes failu.

4. Tiek noteikta nepareiza valsts

Tas var notikt, ja vietne darbojas caur proxy, CDN vai Cloudflare. Šādā gadījumā REMOTE_ADDR var būt starpservera IP adrese, nevis pircēja IP adrese.

Iespējamās galvenes:

HTTP_CF_CONNECTING_IP
X-Forwarded-For

Tās jāizmanto tikai pareizi konfigurēta uzticama proxy gadījumā. Pretējā gadījumā ļaunprātīgs lietotājs var ievietot patvaļīgu IP adresi galvenē.

5. Pēc maksājuma izvēles pasūtījums netiek izveidots

Šādā gadījumā jāpārbauda:

• front-kontrolieris validation.php;
• validateOrder() izsaukums;
• vai ir aktīvs grozs;
• vai ir klients;
• pasūtījuma statuss;
• PrestaShop žurnāli;
• PHP-FPM vai Apache žurnāli.

Drošība un privātums

Modulis strādā ar pircēja IP adresi, tāpēc ir svarīgi ievērot vairākus noteikumus:

• nerādīt pircēja IP adresi publiskās lapās;
• bez vajadzības neglabāt liekus IP žurnālus;
• neglabāt GeoIP datubāzi publiskajā vietnes mapē;
• neizmantot GeoIP kā vienīgo juridiski nozīmīgo kritēriju strīdīgos ierobežojumos;
• atstāt pircējam alternatīvu maksājuma veidu;
• ņem vērā, ka VPN gadījumā valsts var tikt noteikta nepareizi.

Ieteicamā izstrādes darba shēma

Droša shēma veikala administratoram izskatās šādi:

1. Izveidot veikala kopiju testa domēnā.
2. Izveidot moduļa mapi /modules/ direktorijā.
3. Uzstādīt Composer atkarības.
4. Pieslēgt GeoLite2 Country datubāzi.
5. Izveidot pamata maksājumu moduli.
6. Pievienot bankas rekvizītu iestatījumus.
7. Pievienot atļauto valstu sarakstu.
8. Pārbaudīt attēlošanu checkout sadaļā.
9. Pārbaudīt pasūtījuma izveidi.
10. Pārbaudīt e-pastus.
11. Iepakot moduli ZIP arhīvā.
12. Uzstādīt moduli dzīvajā veikalā.
13. Notīrīt kešatmiņu.
14. Izveidot testa pasūtījumu.

Pirms jebkādām izmaiņām dzīvajā vietnē vēlams izveidot rezerves kopiju:

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

Kas jāzina veikala administratoram

Lai strādātu ar šādu moduli, nav obligāti jābūt profesionālam programmētājam, bet jāzina pamata lietas:

• kas ir modules mape;
• kā augšupielādēt ZIP moduli PrestaShop;
• kā notīrīt kešatmiņu;
• kā pārbaudīt PHP kļūdas;
• kā strādāt caur SSH;
• kā pārbaudīt faila tiesības;
• kā atšķirt testa vietni no dzīvas vietnes;
• kā izveidot rezerves kopiju pirms izmaiņām.

Ja veikals darbojas uz VPS, administratoram vēlams nodrošināt piekļuvi:

• SSH;
• PHP CLI;
• Composer;
• PHP, Apache vai Nginx žurnāliem;
• vietnes failiem.

Noslēgums

Maksājumu modulis ar pircēja valsts ierobežojumu ir praktisks risinājums veikaliem, kuriem nepieciešams elastīgi pārvaldīt pieejamos maksājuma veidus. To var izveidot pēc standarta bankas pārskaitījuma loģikas, bet labāk noformēt kā atsevišķu neatkarīgu moduli.

Galvenie šāda risinājuma elementi:

• atsevišķs payment module;
• mantošana no PaymentModule;
• pasūtījuma izveide ar validateOrder();
• bankas rekvizītu iestatījumi;
• atļauto valstu saraksts;
• GeoLite2 Country datubāze;
• MaxMind GeoIP2 bibliotēka;
• droša datubāzes glabāšana ārpus public_html;
• testēšana staging kopijā.

Šāda pieeja ļauj nesabojāt standarta bankas pārskaitījuma moduli, neiejaukties PrestaShop kodolā un saglabāt iespēju drošāk atjaunināt veikalu nākotnē.

🧩 Nepieciešams maksājumu modulis PrestaShop veikalam?

SOLLER.LV palīdz izveidot un pielāgot PrestaShop moduļus: maksājumu veidus, piegādes integrācijas, preču importu, GeoIP ierobežojumus, checkout loģiku un e-komercijas automatizācijas risinājumus.