Etusivu Tuotteet VirtueMart Ohjelmistokehys Asennus ja konfigurointi

VirtueMartin verkkomaksuohjelmistojen asennus ja konfigurointi

Tämän ohjeen kuvakaappaukset on otettu VirtueMart 1.1.3-versiosta. VirtueMart 1.0.x, 1.1.x ja ja 1.2.x poikkeavat toisistaan ulkonäöltä, mutta asennuksen ja konfiguroinnin osalta menettelytapa on sama versiosta riippumatta.

Jakelupaketit

Aivomatic Oy:n VirtueMart-verkkokauppaohjelmistolle kehittämät verkkomaksuohjelmat toimitetaan aina kahdessa eri osassa. Kumpikin osa on pakattu erilliseen jakelupakettiin.

Ensimmäinen jakelupaketti sisältää kaikille maksutavoille yhteisen ohjelmistokehyksen. Ohjelmistokehys on siis perusta, jonka päälle maksutapaspesifiset modulit lisätään. Jos verkkokauppaan asennetaan useita eri verkkomaksumoduleja, riittää, että yhteinen ohjelmistokehys asennetaan vain kerran.

Toinen jakelupaketti sisältää tietylle verkkomaksutavalle spesifisen ohjelmistomodulin tiedostot.

Jakelupakettien nimet

Ohjelmistokehyksen jakelupaketti. Esim:

  • FipnVm_J10_ISO-8859-1_0.8.3.zip
  • FipnVm_J15_UTF-8_0.8.3.zip

Maksutapaspesifisen modulin jakelupaketti. Esim:

  • FipnVmSvm_J10_ISO-8859-1_0.9.1.zip
  • FipnVmSvm_J15_UTF-8_0.9.1.zip

Yllä olevissa esimerkeissä J10 ja J15 tarkoittavat Joomla-sisällönhallintajärjestelmän versiota (1.0.x tai 1.5.x) jolle paketti on tarkoitettu. ISO-8859-1 ja UTF-8 tarkoittavat tiedostoissa käytettyä merkistökoodausta (ns. character set). 0.8.3 ja 0.9.1 tarkoittavat jakelupaketin sisältämän ohjelman versiota.

Paketin nimi FipnVm viittaa VirtueMartille tarkoitettuun ohjelmistokehykseen. FipnVmSvm viittaa Suomen Verkkomaksuun, FipnVmLk Luottokuntaan jne.

Jakelupakettien hakemistorakenne ja purkaminen

Kaikki jakelupaketit sisältävät samanlaisen Joomlan ja VirtueMartin hakemistoihin täsmäävän hakemistorakenteen. Sekä yhteinen ohjelmistokehys että maksutapaspesifiset modulit puretaan Joomlan administrator-hakemiston alle.

Paketit voi esim. purkaa omalle tietokoneelle ja siirtää puretut tiedostot FTP:llä verkkokaupan palvelimelle, tai paketit voi purkaa suoraan palvelimella.

Hakemistorakenteen havainnollistamiseksi alla on esimerkkejä jakelupakettien sisällöstä ja hakemistorakenteesta erikseen ja yhdessä.

Ao. esimerkkien selkeyttämiseksi hakemistoa /administrator/components/com_virtuemart/classes/aivomatic/doc eli dokumentaatiohakemistoa ei esitetän kokonaisuudessaan. Sitä ei myöskään ole välttämätöntä siirtää verkkokaupan palvelimelle.

FipnVm

Kaikille maksutavoille yhteinen ohjelmistokehys yksinään ilman maksutapaspesifisiä lisämoduleja.

.
`-- administrator
    `-- components
        `-- com_virtuemart
            |-- classes
            |   `-- aivomatic
            |       |-- Fipn
            |       |   |-- CHANGELOG
            |       |   |-- Exception.php
            |       |   |-- Factory.php
            |       |   |-- LICENSE_COPYRIGHT
            |       |   |-- Pear
            |       |   |   |-- LICENSE
            |       |   |   `-- Validate.php
            |       |   |-- Receiver.php
            |       |   |-- Sender.php
            |       |   `-- Validator.php
            |       |-- Fipn.php
            |       |-- doc
            |       |   `-- fipnvm
            |       `-- fipnvm
            |           |-- CHANGELOG
            |           |-- LICENSE_GPLv2
            |           `-- fipnvm_base.php
            `-- html
                `-- checkout.fipnvm.php

FipnVmSvm

FipnVmSvm eli Suomen Verkkomaksut Oy:n maksupalvelulle tarkoitettu maksumoduli yksinään ilman ohjelmistokehystä.

.
`-- administrator
    `-- components
        `-- com_virtuemart
            `-- classes
                |-- aivomatic
                |   |-- Fipn
                |   |   |-- Receiver
                |   |   |   `-- SuomenVerkkomaksut.php
                |   |   |-- Sender
                |   |   |   `-- SuomenVerkkomaksut.php
                |   |   |-- Util
                |   |   |   `-- SuomenVerkkomaksut
                |   |   |       `-- ButtonGrid.php
                |   |   `-- Validator
                |   |       `-- SuomenVerkkomaksut.php
                |   |-- doc
                |   |   `-- fipnvmsvm
                |   `-- fipnvm
                |       |-- lang
                |       |   |-- ps_suomenverkkomaksut.en_US.php
                |       |   `-- ps_suomenverkkomaksut.fi_FI.php
                |       `-- suomenverkkomaksut
                |           |-- CHANGELOG
                |           |-- LICENSE
                |           |-- README
                |           |-- checkout.suomenverkkomaksut.en_US.html
                |           |-- checkout.suomenverkkomaksut.fi_FI.html
                |           |-- formExtraInfo.suomenverkkomaksut.php
                |           |-- index.html
                |           |-- payhere_eng.jpg
                |           `-- payhere_fin.jpg
                `-- payment
                    |-- ps_suomenverkkomaksut.cfg.php
                    `-- ps_suomenverkkomaksut.php

FipnVm ja FipnVmSvm yhdessä

FipnVm-ohjelmistokehys ja FipnVmSvm-moduli yhdessä.

.
`-- administrator
    `-- components
        `-- com_virtuemart
            |-- classes
            |   |-- aivomatic
            |   |   |-- Fipn
            |   |   |   |-- CHANGELOG
            |   |   |   |-- Exception.php
            |   |   |   |-- Factory.php
            |   |   |   |-- LICENSE_COPYRIGHT
            |   |   |   |-- Pear
            |   |   |   |   |-- LICENSE
            |   |   |   |   `-- Validate.php
            |   |   |   |-- Receiver
            |   |   |   |   `-- SuomenVerkkomaksut.php
            |   |   |   |-- Receiver.php
            |   |   |   |-- Sender
            |   |   |   |   `-- SuomenVerkkomaksut.php
            |   |   |   |-- Sender.php
            |   |   |   |-- Util
            |   |   |   |   `-- SuomenVerkkomaksut
            |   |   |   |       `-- ButtonGrid.php
            |   |   |   |-- Validator
            |   |   |   |   `-- SuomenVerkkomaksut.php
            |   |   |   `-- Validator.php
            |   |   |-- Fipn.php
            |   |   |-- doc
            |   |   |   |-- fipnvm
            |   |   |   `-- fipnvmsvm
            |   |   `-- fipnvm
            |   |       |-- CHANGELOG
            |   |       |-- LICENSE_GPLv2
            |   |       |-- fipnvm_base.php
            |   |       |-- lang
            |   |       |   |-- ps_suomenverkkomaksut.en_US.php
            |   |       |   `-- ps_suomenverkkomaksut.fi_FI.php
            |   |       `-- suomenverkkomaksut
            |   |           |-- CHANGELOG
            |   |           |-- LICENSE
            |   |           |-- README
            |   |           |-- checkout.suomenverkkomaksut.en_US.html
            |   |           |-- checkout.suomenverkkomaksut.fi_FI.html
            |   |           |-- formExtraInfo.suomenverkkomaksut.php
            |   |           |-- index.html
            |   |           |-- payhere_eng.jpg
            |   |           `-- payhere_fin.jpg
            |   `-- payment
            |       |-- ps_suomenverkkomaksut.cfg.php
            |       `-- ps_suomenverkkomaksut.php
            `-- html
                `-- checkout.fipnvm.php

Ohjelmistokehys ja kaksi modulia yhdessä

FipnVm-kehys sekä FipnVmLk- (Luottokunta) ja FipnVmNp- (Nordea Pankki) modulit kaikki yhdessä. Tämä havainnollistaa, miten useamman modulin asentaminen tapahtuu.

.
`-- administrator
    `-- components
        `-- com_virtuemart
            |-- classes
            |   |-- aivomatic
            |   |   |-- Fipn
            |   |   |   |-- CHANGELOG
            |   |   |   |-- Exception.php
            |   |   |   |-- Factory.php
            |   |   |   |-- LICENSE_COPYRIGHT
            |   |   |   |-- Pear
            |   |   |   |   |-- LICENSE
            |   |   |   |   `-- Validate.php
            |   |   |   |-- Receiver
            |   |   |   |   |-- Luottokunta.php
            |   |   |   |   `-- NordeaPankki.php
            |   |   |   |-- Receiver.php
            |   |   |   |-- Sender
            |   |   |   |   |-- Luottokunta.php
            |   |   |   |   `-- NordeaPankki.php
            |   |   |   |-- Sender.php
            |   |   |   |-- Validator
            |   |   |   |   |-- Luottokunta.php
            |   |   |   |   `-- NordeaPankki.php
            |   |   |   `-- Validator.php
            |   |   |-- Fipn.php
            |   |   |-- doc
            |   |   |   |-- fipnvm
            |   |   |   |-- fipnvmlk
            |   |   |   `-- fipnvmnp
            |   |   `-- fipnvm
            |   |       |-- CHANGELOG
            |   |       |-- LICENSE_GPLv2
            |   |       |-- fipnvm_base.php
            |   |       |-- lang
            |   |       |   |-- ps_luottokunta.en_US.php
            |   |       |   |-- ps_luottokunta.fi_FI.php
            |   |       |   |-- ps_nordeapankki.en_US.php
            |   |       |   `-- ps_nordeapankki.fi_FI.php
            |   |       |-- luottokunta
            |   |       |   |-- CHANGELOG
            |   |       |   |-- LICENSE
            |   |       |   |-- checkout.luottokunta.en_US.html
            |   |       |   |-- checkout.luottokunta.fi_FI.html
            |   |       |   |-- formExtraInfo.luottokunta.php
            |   |       |   |-- luottokunta.gif
            |   |       |   `-- visa-electron-mastercard-amex-223x40.png
            |   |       `-- nordeapankki
            |   |           |-- CHANGELOG
            |   |           |-- LICENSE
            |   |           |-- checkout.nordeapankki.en_US.html
            |   |           |-- checkout.nordeapankki.fi_FI.html
            |   |           |-- formExtraInfo.nordeapankki.php
            |   |           `-- nordea-50x50.gif
            |   `-- payment
            |       |-- ps_luottokunta.cfg.php
            |       |-- ps_luottokunta.php
            |       |-- ps_nordeapankki.cfg.php
            |       `-- ps_nordeapankki.php
            `-- html
                `-- checkout.fipnvm.php

Kaikille maksumoduleille yhteisten tilauksen tilatyyppien konfigurointi

Kaikki VirtueMartin maksumodulit käyttävät alla kuvattuja tilauksen tilatyyppejä. Ne tulee luoda ennen ensimmäisen maksumodulin käytöönottoa. Myöhempien lisämodulien asennuksen yhteydessä niitä ei tarvitse luoda enää uudelleen.

Tilauksen tilatyyppien lisäys

Lisätään kaksi uutta tilauksen tilatyyppiä.

Kirjaudu sisään Joomla-ohjauspaneliin. Avaa VirtueMart hallintapaneli (Komponentit / VirtueMart).

Tilatyyppi E

Valitse Tilaukset / Lisää tilauksen tilatyyppi.

Syötä seuraavat tiedot:

  • Tilauksen tilan koodi = E
  • Tilauksen tilan nimi = Error (Nimien suomenkielisistä käännöksistä enemmän tuonnempana.)
  • Luettelojärjestys = 6 (Jos tilaustyyppejä on lisätty jo ennestään, luku saattaa olla suurempikin. Luku ei kuitenkaan ole kriittinen.)
  • Klikkaa lopuksi Tallenna
Tilatyyppi E

Tilatyyppi W

Valitse Tilaukset / Lisää tilauksen tilatyyppi.

Syötä seuraavat tiedot:

  • Tilauksen tilan koodi = W
  • Tilauksen tilan nimi = Warning
  • Luettelojärjestys = 7
  • Klikkaa lopuksi Tallenna
Tilatyyppi W

Checkout-modulin Delayed-tilatyyppi

Checkout-verkkomaksupalvelun ohjelmistomoduli FipnVmChk vaatii lisäksi neljännen uuden tilatyypin:

  • Tilauksen tilan koodi = D
  • Tilauksen tilan nimi = Delayed (suom. esim. Viivästetty)
  • Luettelojärjestys = 8

Lisätietoja tilauksen tilatyypeistä

Vakiona VirtueMartissa on viisi tilauksen tilatyyppiä (ao. kuvan listassa kohdat 1-5). Kohdat 6-7 ovat tämän ohjeen mukaisesti lisätyt tilauksen tilatyypit.

Tilatyyppien luettelo

VirtueMart olettaa, että tilauksen tilatyypit 1-5 ovat olemassa. Niiden nimet voi kääntää suomeksi (etenkin kun ne näkyvät sellaisenaan asiakkaalle lähetettävässä tilausviestissä), mutta tilan koodin tunnuskirjainta ei pidä muuttaa. Myös kohtien 6-7 nimet voi kääntää, ja periaatteessa niille voi antaa toiset koodikirjaimet, mutta selvyyden vuoksi kannattanee pitäytyä näissä, jolloin tämän ohjeen seuraaminen on helpompaa.

Jos haluat suomentaa tilauksen tilan nimet, yksi mahdollinen malli voisi olla seuraava:

  • P (Pending) = Odottaa
  • C (Confirmed) = Vahvistettu
  • X (Cancelled) = Peruttu
  • R (Refunded) = Maksu palautettu
  • S (Shipped) = Lähetetty
  • E (Error) = Virhe
  • W (Warning) = Varoitus

Kannattaa kuitenkin huomioida, että VirtueMartissa ei pysty kääntämään tilauksen tilatyyppien nimiä useammalle eri kielelle samanaikaisesti.

Maksumodulin käyttöönotto ja konfigurointi

Kaikkien maksumodulien käyttöönoton ensimmäinen vaihe, eli Maksutapalomake-välilehden asetusten syöttö, on saman kaltainen. Ohjeet alla.

Valitse Kaupan hallinta / Lisää maksutapa. Kts. ao. kuva.

  • Käytössä?
    • Ota ruksi aluksi pois, jotta maksumoduli ei tule julkiseen käyttöön verkkokaupassa, ennen kuin se on konfiguroitu valmiiksi asti. Aseta ruksi päälle, kun haluat uuden maksumodulin käyttöön.
  • Maksulomakkeen nimi
    • Periaatteessa tähän voi kirjoittaa minkä vain maksutapaa hyvin kuvaavan nimityksen. Tämä nimi näkyy myös asiaakkalle maksutapojen valinnassa. Jotkin maksupalvelujen tarjoajat antavat tarkempia ohjeita verkkomaksun oikeasta nimeämisestä.
  • Koodi
    • Enintään kahdeksan kirjainta pitkä koodi, joka yksilöi maksutavan. Kahdella eri maksutavalla ei saa olla samaa koodia. Esim. SUOMENVM tai LUOTTOK
  • Maksutapaluokan nimi
    • Valitse maksumoduli alasvetovalikosta, jossa modulien nimet näkyvät muodossa ps_palveluntarjoaja eli esim. ps_suomenverkkomaksut tai ps_nordeapankki. Käytännössä nimi on hakemistossa /administrator/components/com_virtuemart/classes/payment olevan PHP-tiedoston nimen alkuosa. VirtueMart 1.0.x:ssä nimeä ei voi valita alasvetovalikosta, vaan se pitää kirjoittaa käsin.
  • Maksutapatyyppi
    • Valitse HTML-Form

Alaosan muut kentät eivät ole pakollisia. Koska niiden toiminnasta vastaa VirtueMart eikä maksumoduli, ei niitä siksi käydä tässä läpi sen tarkemmin. Lyhyesti todettakoon, että kentät vaikuttavat siihen, onko maksutapa vain jonkun tietyn asiakasryhmän käytössä, annetaanko asiakkaalle hinnanalennus (tai korotus) siitä hyvästä, että hän käyttää tätä tiettyä maksutapaa, ja jos niin onko alennus kiinteä summa tai prosenttiosuus tilauksen kokonaissummasta, ja minkä suuruinen alennus/korotus enintään tai vähintään on. Luettelojärjestyksellä maksutavat voidaan esittää asiakkaalle jossain tietyssä halutussa järjestyksessä.

Klikkaa Käytä.

Avaa seuraavaksi maksutapalomakkeen Asetukset-välilehti. Sen asetukset kuvataan tarkemmin kunkin maksumodulin erillisessä asennusohjeessa.

maksutapalomake

Maksutapojen valinnan rajoittaminen

Vakiona VirtueMartissa ei ole mitään keinoa rajoittaa eri maksutapojen näkymistä asiakkaalle esitettävällä maksutapojen valintalistalla. Tuki maksutapojen käytön rajoittamiselle voidaan kuitenkin toteuttaa yksinkertaisella lisäyksellä yhteen VirtueMartin tiedostoon.

VirtueMartia ei ole tekniseltä tai Fipn-modulien käyttämisen kannalta välttämätöntä muokata. Ilman oheista VirtueMartin muokkausta maksutapojen valitsemista ei kuitenkaan voida rajata esim. ostoskorin summan mukaisesti.

Jos VirtueMartiin asennetaan sen oma päivitys, joka korvaa vanhan ao. ohjeen mukaan muokatun ps_payment_method.php -tiedoston, muokkaukset ja lisäykset pitää tehdä uudelleen.

ps_payment_method::list_payment_radio() -metodin muokkaus

Lisää ../administrator/components/com_virtuemart/classes/ps_payment_method.php -tiedostossa olevan ps_payment_method -luokan list_payment_radio() -metodin loppussa olevaan while-silmukkaan if ($this->paymentMethodAvailable($db->f("payment_method_id"))) { -rivi ja sitä vastaava sulkeva }-merkki ao. esimerkin mukaisesti:

 
/**
 * Returns all payment_methods with given selector in a Radiolist
 *
 * @param string $selector A String like "B" identifying a type of payment methods
 * @param int $payment_method_id An ID to preselect
 * @param boolean $horiz Separate Items with Spaces if true, else with 
 
 * @return string
 */
function list_payment_radio($selector, $payment_method_id, $horiz) {
    global $CURRENCY_DISPLAY, $ps_checkout;
 
    // ... koodia ...
 
    $db->query($q);
    $has_result = false;
    // Start radio list
    while ($db->next_record()) {
        if ($this->paymentMethodAvailable($db->f("payment_method_id"))) {
            $has_result = true;
 
            // ... koodia ...
 
            echo "</label>";
            if ($horiz) {
                echo(" ");
            } else {
                echo("<br />");
            }
        }
    }
    return $has_result;
}
 

ps_payment_method::paymentMethodAvailable() -metodin lisäys

Lisää ps_payment_method.php -tiedostoon (esim. heti list_payment_radio() -metodin perään) uusi paymentMethodAvailable() -metodi ao. esimerkin mukaan:

 
/**
 * Returns boolean availability status of a payment method
 *
 * Returns true if payment method is available or if payment method doesn't
 * support paymentMethodAvailable()-functionality, false if not available.
 *
 * @param int $paymentMethodId
 * @return boolean
 */
function paymentMethodAvailable($paymentMethodId)
{
    $paymentSqlQuery = $this->payment_sql($paymentMethodId);
    $className = $paymentSqlQuery->f('payment_class');
    $filename = CLASSPATH.'payment/'.$className.'.php';
    if (file_exists($filename)) {
        include_once $filename;
        if (class_exists($className)) {
            try {
                $PaymentMethod = new $className();
            } catch (Exception $e) {
                return true;
            }
            if (method_exists($PaymentMethod, 'isAvailable')) {
                try {
                    $booleanStatus = $PaymentMethod->isAvailable();
                } catch (Exception $e) {
                    return true;
                }
                return $booleanStatus;
            }
        }
    }
    return true;
}