Paytrail PSP

1. Mikä tämä on

Paytrail PSP -maksumoduuli tuo Zen Cart -verkkokauppaasi Paytrailin (aiemmin Checkout Finland) maksutavat: verkkopankit, korttimaksut, mobiilimaksut sekä lasku- ja osamaksupalvelut. Sama moduuli toimii Zen Cartin versioissa1.5.6 ja2.2.2.

Asiakkaan puolella moduuli näyttää maksutavat kassalla ja ohjaa asiakkaan maksamaan. Kauppiaan puolella se antaa tilaussivulle oman paneelin, josta hoituvat kolme asiaa:laskun aktivointi,maksulinkin lähettäminen jahyvitys.

2. Vaatimukset ennen käyttöönottoa

Paytrail tilittääeuroina, ja moduuli kertoo Paytrailille sen summan ja sen valuutan, jonka asiakas kaupassa näki. Siksi kaupan omien asetusten on oltava kunnossa. Alla mitä tarvitaan — ja luvussa 4 miten moduuli tekee tämän kaiken puolestasi.

Moduuli ei kysy arvonlisäveroprosenttia missään. Se lukee sen kaupan omista verotaulukoista samalla tavalla kuin Zen Cart laskee asiakkaalta perittävän veron. Näin käsin kirjoitettu prosentti ei voi olla ristiriidassa sen kanssa, mitä asiakkaalta oikeasti veloitettiin.

Muut vaatimukset: Zen Cart 1.5.6 (PHP 7.4) tai 2.2.2 (PHP 8.2+), PHP-laajennukset curl ja json.

3. Asetukset — kaikki kaksitoista

Asetukset löytyvät kohdastaAdmin → Modules → Payment → Paytrail PSP → Edit. Alla jokainen asetus, sen merkitys ja oletusarvo.

Kuva 1. Moduulin kaikki kaksitoista asetusta hallinnan maksumoduulisivulla. Kuvassa näkyvät Paytrailin testitunnukset.

4. Suomen paikallisuuden tarkistus

Luvun 2 asetukset ovat viidellä eri hallintasivulla, ja jokainen niistä on sellainen, että väärin jäänyt kohta ei näy virheenä vaan rahana. Siksi moduuli osaa tehdä ne puolestasi.

Admin → Modules → Payment → Paytrail PSP → Suomen paikallisuuden tarkistus = Kyllä, ja tallenna. Tarkistus ajetaan seuraavan kerran kun moduuli ladataan — käytännössä heti, koska hallinnan moduulisivu lataa moduulin.

Mitä se tekee, riippuvuusjärjestyksessä

Jokainen askel kysyy kolme kysymystä tässä järjestyksessä: onko edellytykseni kunnossa, onko asia jo oikein, ja vasta sitten tekee. Askel jonka edellytys puuttuu kertoo mikä puuttuu eikä pysäytä niitä askeleita, jotka eivät siitä riipu.

1. euro on olemassa valuuttana
2. euro on perusvaluutta kurssilla 1.0
3. euro on kaupan oletusvaluutta
4. Suomi on kaupan tuntema maa
5. kauppa sijaitsee Suomessa, ja STORE_ZONE on järkevä
6. verovyöhyke kattaa koko Suomen,kertaalleen
7. tuotteilla on 25,5 %
8. toimituksella on 25,5 %
9. käytössä olevilla toimitustavoilla on veroluokka
10. hinnat näytetään verollisina
11. todennus: mitä kauppa nyt oikeasti perii

Turvallinen toistaa

Se on tavoite eikä sivuvaikutus: kauppias joka ei tiedä toimiko se, painaa sitä uudelleen — eikä siitä saa rangaista. Jokaista kirjoitusta edeltää haku, eikä valmiiksi kunnossa olevaa kosketa mikään.

Kaksoiskappaleet ovat se mikä oikeasti kaataa tämän. Zen Cart laskee verokannat yhteen eikä korvaa niitä toisillaan, joten kaksi kantaa samalle luokalle ja vyöhykkeelle tekee 51 % tai 57,5 %. Sama tapahtuu jos maa on liitetty vyöhykkeeseen kahdesti — eikä siitä näy verokantasivulla mitään. Tarkistus poistaa nämä ennen kuin tekee mitään muuta. Veroluokan kaksoiskappaleista se vain kertoo eikä poista niitä, koska tuotteet voivat viitata niihin.

Raportti

Ajosta jää tiedosto logs/paytrailpsp-localisation-<aika>.log, rivi per askel etuliitteellä OK, DONE, SKIP tai FAIL, ja lopuksi yhteenveto:

OK   euro on kaupan valuutta (2)
OK   euron kurssi on jo 1.0
OK   STORE_ZONE on 0 eli koko maa — Suomella ei ole osavaltioita
OK   verovyöhyke "Finland" on olemassa (2)
OK   Suomi on vyöhykkeessä kertaalleen, koko maa
DONE verokanta toimituksen luokalle päivitettiin 25,50 %:iin (oli 24.0000)
OK   TODENNETTU: kaupan taulut antavat tuotteiden verokannaksi 25,50 %
OK   TODENNETTU: 100,00 netto + 25,50 vero = 125,50 brutto
OK   TODENNETTU: kauppa itse vastaa 25,50 %
------------------------------------------------------------
yhteensä: 1 muutettu, 23 oli jo kunnossa, 0 ohitettu, 0 epäonnistui

Nolla muutosta toisella painalluksella on se, miltä kunnossa oleva kauppa näyttää.

5. Mitä asiakas näkee

Asiakas valitsee kassalla maksutavan Paytrailin logolistasta. Lista tulee suoraan Paytraililta, joten siinä ovat aina ne maksutavat, jotka kauppiastunnuksellesi on avattu.

Kuva 2. Maksutavat kassalla: verkkopankit, mobiilimaksut, kortit sekä lasku- ja osamaksupalvelut.

Valinnan jälkeen asiakas siirtyy Paytrailin sivulle ja sieltä valitsemansa pankin tai palvelun sivulle. Maksun jälkeen hän palaa kauppaan ja tilaus syntyy.

Jos asiakas ei palaa

Paytrail ilmoittaa maksusta kaupallekahta reittiä: asiakkaan selaimella ja erikseen palvelimelta palvelimelle. Kumpi ehtii ensin, se luo tilauksen; toinen huomaa työn tehdyksi eikä tee sitä toiseen kertaan. Käytännön merkitys kauppiaalle:tilaus syntyy vaikka asiakas sulkisi selaimen heti maksun jälkeen.

Jos asiakas keskeyttää maksun tai pankki hylkää sen, tilausta ei synny ja asiakkaan kesken jääneet maksuyritykset siivotaan pois. Näin seuraava maksuyritys alkaa puhtaalta pöydältä.

Mitä Paytrailille kerrotaan tilauksesta

Moduuli lähettää Paytrailille tilauksen rivit eriteltyinä: jokainen tuote omanaan, alennukset omana rivinään, toimituskulut omanaan. Summat ovat verollisia, koska niin Paytrail ne odottaa.

Kuva 3. Sama tilaus kaupan tilaussivulla: tuote 100,00 netto, toimitus 12,55, ALV 25,5 % 28,05 ja loppusumma 138,05.

Erittely merkitsee erityisesti lasku- ja osamaksupalveluissa, jotka näyttävät rivit asiakkaalle sellaisenaan.

6. Tilaussivun Paytrail-paneeli

Kun tilaus on maksettu Paytraililla, tilauksen käsittelysivun alalaidassa onPaytrail PSP -paneeli. Se on sivun lopussa, ennen alatunnistetta, ja auki valmiiksi — sitä ei tarvitse etsiä minkään avattavan takaa.

Kuva 4. Paneelin kolme osiota viivoilla erotettuna: laskun aktivointi, maksulinkki sähköpostilla ja hyvitys.

Ylinnä ovatmaksutapahtuman tiedot: tapahtumatunnus, aika ja tilausnumero. Tunnus on se, jolla maksu löytyy Paytrailin omasta hallinnasta, joten se kannattaa ottaa mukaan jos maksusta joutuu kysymään Paytrailin tuesta.

Sen alla kolme osiota, aina tässä järjestyksessä:

1. Laskun aktivointi — vain jos tilaus on maksettu laskulla. Ylimpänä siksi, että lasku jota kukaan ei aktivoi on tilaus joka lähtee eikä laskuta.
2. Maksulinkki sähköpostilla — rahan perimistä, jota ei ole vielä tullut.
3. Hyvitys — rahan palauttamista, viimeisenä, koska se on ainoa jota ei saa peruttua painamalla uudelleen.

7. Laskun aktivointi

Osa maksutavoista on laskuja eikä maksuja: asiakkaan tilaus on hyväksytty ja raha taattu, muttalaskua ei ole lähetetty. Se lähtee vasta kun sanot että tavara lähtee.

Osio näkyyvain jos tilaus on maksettu maksutavalla, joka tarjoaa manuaalisen laskun aktivoinnin — oletuksena walleyb2c, walleyb2b ja klarna. Tavallinen korttitilaus ei näytä tätä osiota lainkaan.

Kuva 5. Lasku odottaa aktivointia. Arkistointitunnus on Paytrailin antama viite tälle laskulle.

• Aktivoi lasku — Paytrail lähettää laskun asiakkaalle.
• Peruuta lasku — tilaus ei lähde, joten laskua ei synny koskaan.

Napit ovat kaksi eri lomaketta, eivät yksi kahdella napilla: eksynyt Enter-painallus lähettäisi muuten sen, kumman selain sattuu katsomaan ensimmäiseksi.

Kuva 6. Aktivoitu lasku: nappeja ei enää näytetä, ja aktivoinnin päivämäärä jää näkyviin.

Kuva 7. Peruutettu lasku. Tätä laskua ei lähetetä koskaan.

Anna laskutilauksille oma tila

Tämä on se kohta, joka tekee koko ominaisuudesta turvallisen. Laskulla maksettu tilaus ei ole sama asia kuin maksettu tilaus: asiakas on sitoutunut ja Paytrail takaa summan, mutta mitään ei ole laskutettu eikä laskuteta ennen kuin joku painaa Aktivoi.

Jos molemmat päätyvät samaan tilaan, laskutilaus näyttää tilauslistassa selvitetyltä — ja ainoa paikka, jossa asia näkyy, on tämän sivun Paytrail-paneeli, jota kukaan ei avaa tilaukselta joka näyttää jo hoidetulta. Tavara lähtee laskua vastaan, jota ei ole lähetetty.

Admin → Modules → Payment → Paytrail PSP → Tilauksen tila, kun maksettu laskulla. Valitse tila, joka erottuu tavallisesta. Mikä tila se on ja miltä se kuulostaa, on sinun päätöksesi — moduuli tarjoaa vain paikan, johon se kiinnittyy.

Asetus on oletuksena tyhjä, jolloin käytetään tavallista tilaa eikä mikään muutu. Vanhaa kauppaa päivitettäessä käyttäytyminen pysyy siis ennallaan, kunnes kauppias itse valitsee toisin.

Ja toinen tila: kun lasku on lähetetty

Pelkkä odotustila ei vielä riitä. Kun olet painanut Aktivoi lasku, tilauksen pitää myös siirtyä eteenpäin — muuten tilauslistassa näyttää edelleen siltä että jotain on tekemättä, eikä hoidettua erota hoitamattomasta.

Tilauksen tila, kun lasku on aktivoitu on tätä varten. Kun se on asetettu, yksi painallus tekee kolme asiaa:

1. tilaus siirtyy valitsemaasi tilaan,
2. tilaushistoriaan tulee merkintä "Laskutus on aktivoitu",
3. asiakkaalle lähtee ilmoitus, että lasku on matkalla.

Kolmas kohta on siellä siksi, että asiakas saa pian laskun eikä mikään muu tässä kulussa kerro siitä hänelle. Viesti menee asiakkaan omalla kielellä, kuten maksulinkinkin viesti — sanamuodot ovat tiedostossa paytrailpsp_invoice_email.php, katso luku 11.

Tilaushistorian rivi merkitään asiakkaalle ilmoitettu vain jos viesti oikeasti lähti. Jos kaupan sähköpostitus on pois päältä, rivi kertoo sen — merkintä joka väittää ilmoittaneensa ilman että mitään lähti olisi valhe juuri siinä paikassa, josta asia tarkistetaan kun asiakas sanoo ettei kuullut mitään.

Tilat ovat sinun, eivät moduulin

Moduuli ei luo eikä pakota yhtäkään tilaa. Se ei tiedä miltä sinun prosessisi näyttää, eikä sen kuulu tietää. Se tarjoaa kaksi kohtaa, joissa tilaus voi siirtyä eteenpäin — kun lasku syntyy ja kun se lähetetään — ja jättää sinulle sen, mitä ne kohdat tarkoittavat.

Tilat luodaan kaupan omasta hallinnasta: Admin → Localization → Orders Status. Sen jälkeen ne valitaan moduulin asetuksista. Jos jätät asetukset tyhjiksi, mitään ei tapahdu — ominaisuus on olemassa vasta kun otat sen käyttöön.

Muutama esimerkki siitä mihin näitä on käytetty. Nämä ovat ideoita, eivät ohjeita:

• Kaksi tilaa, yksinkertaisin tapa. "Odottaa laskutusta" ja "Laskutettu". Tilauslistasta näkee yhdellä silmäyksellä kumpaa on tekemättä.
• Varasto ennen laskua. Laskutilaukset omaan tilaansa, jota varastotyö seuraa: lasku aktivoidaan vasta kun paketti on oikeasti lähdössä, jolloin asiakas ei saa laskua tavarasta jota ei lähetetty.
• Erillinen tarkistus isoille summille. Laskutilaukset jäävät tilaan, jota joku käy läpi ennen aktivointia — luottoriski on laskukaupassa kauppiaan, ei Paytrailin.
• Ei mitään. Jätä asetukset tyhjiksi. Laskut toimivat silti, aktivointi toimii silti, tilat pysyvät ennallaan.

Jos et halua käyttää ominaisuutta lainkaan, asetaLaskun manuaalinen aktivointi = Ei. Silloin Paytrail aktivoi laskut itse, kuten muutkin maksut, eikä osiota näy.

8. Maksulinkki sähköpostilla

Maksulinkki onmaksupyyntö, ei maksu. Kun lähetät linkin, Paytrailiin ei oteta yhteyttä lainkaan — asiakkaalle lähtee sähköposti, jossa on tilaus, kuvaus, summa ja osoite.

Maksutapahtuma syntyy vasta kun asiakas avaa linkin. Siksiyksi linkki voi tuottaa monta maksutapahtumaa: asiakas joka avaa linkin, miettii ja sulkee välilehden ei ole maksanut mitään, ja voi avata saman linkin huomenna uudelleen.

Paneeli listaa lähetetyt linkit ja jokaisen avauksen sen linkin alla, jolle se kuuluu.Lähetetty mutta ei avattu jaavattu neljästi näyttävät eri asioilta.

Linkin lähettäminen

1. KirjoitaSumma — voi olla koko tilaus tai osa siitä.
2. Kuvaus näkyy asiakkaalle sähköpostissa.
3. Sähköposti on täytetty valmiiksi tilauksen osoitteella.
4. PainaLähetä maksulinkki.

Kun jokin linkin maksutapahtumista maksetaan, linkki merkitään maksetuksi ja tilaus siirtyy maksettuun tilaan. Maksettua tai poistettua linkkiä ei voi avata uudelleen.

9. Hyvitys

Paneelissa on lista tehdyistä hyvityksistä ja lomake uudelle.

Summakenttä on täytetty valmiiksi sillä osalla, jota ei ole vielä hyvitetty: koko maksettu summa kun mitään ei ole hyvitetty, ja loppuosa osittaisen hyvityksen jälkeen. Sen voi korvata pienemmällä summalla.

Hyvitys ei ole valmis silloin kun Paytrail vastaa. Rivi ilmestyy listaan tilassaodottaa pankkia, ja pankin vastattua se muuttuu jokohyvitetty taipankki hylkäsi. Hylätty hyvitys ei vähennä hyvitettävissä olevaa summaa — raha jäi kauppaan.

Samaa tapahtumaa voi hyvittääkerran kolmessa minuutissa. Rajoitus on tahallinen: kahdesti painettu nappi on kahdesti lähetetty raha.

10. Maksuraportit

Moduuli osaa pyytää Paytraililta maksuraportin, joka luetteloi kauppasi maksutapahtumat halutulta ajanjaksolta. Paytrail ei palauta raporttia heti, vaan lähettää sen kaupalle erikseen, kun se on valmis.

Saapuneet raportit tallennetaan hakemistoon ext/paytrailpsp/payment_reports/. Hakemisto on suojattu verkkoselailulta, koska raportti nimeää jokaisen maksun.

11. Kielet ja tekstien muuttaminen

Moduuli ei sisällä kovakoodattua tekstiä. Kaikki mitä asiakas tai kauppias näkee tulee kielitiedostosta:

includes/languages/english/modules/payment/paytrailpsp.php
includes/languages/finnish/modules/payment/paytrailpsp.php

Molemmat määrittelevät täsmälleen samat vakiot. Kolmas kieli syntyy kopioimalla englanninkielinen tiedosto kaupan omaan kielihakemistoon ja kääntämällä arvot.

Maksulinkkisähköpostin teksti

Sähköpostin sanamuodot ovat omassa tiedostossaan paytrailpsp_email.php, jokapalauttaa taulukon sen sijaan että määrittelisi vakioita. Syy: kauppias painaa nappia hallinnassa omalla kielellään, mutta sähköposti menee asiakkaalle asiakkaan kielellä. Vakion voi määritellä vain kerran pyyntöä kohti, joten vakioilla ei voi sanoa "tämä sivu yhdellä kielellä, tuo sähköposti toisella". Taulukolla voi.

Kieli valitaan tässä järjestyksessä: tilauksen kieli, kaupan senhetkinen kieli, englanti, ja lopuksi moduulin sisäinen varateksti.

Laskun aktivoinnin ilmoitus

Sama järjestely, oma tiedostonsa:

includes/languages/<kieli>/modules/payment/paytrailpsp_invoice_email.php

Neljä avainta — SUBJECT, GREETING, INTRO, CLOSING — ja sama kielten hakujärjestys. Ulkoasun voi korvata tiedostolla email/email_template_paytrailpsp_invoice_activated.html.

Maksulinkkisähköpostin ulkoasu

Pudottamalla kauppaan tiedoston email/email_template_paytrailpsp_payment_link.html muotoilet juuri tämän yhden sähköpostin uusiksi koskematta kaikkiin muihin. Kielikohtainen versio menee email/<kieli>/-hakemistoon.

12. Vianselvitys — mihin loki kirjoitetaan

Tekninen seuranta = Kyllä kirjoittaa jokaisesta pyynnöstä tiedoston kaupan lokihakemistoon:

logs/paytrailpsp-<pvm>-<aika>-<prosessi>.log

Tiedostossa on koko tapahtumaketju: asetukset, lähetetty pyyntö, saatu vastaus ja moduulin omat merkinnät. Yksi tiedosto per pyyntö, jotta maksutapahtuman kulku näkyy yhtenä kokonaisuutena.

Viat kirjataan aina, myös kun seuranta on pois päältä:

logs/paytrailpsp-problem-<pvm>.log

Tänne päätyvät esimerkiksi lokalisoinnin epäonnistuminen, paneelin virheet ja lähettämättä jäänyt maksulinkkisähköposti. Vika jota ei kirjata mihinkään on vika jota ei voi selvittää, ja se on eri asia kuin seuranta: seuranta on kauppiaan valinta, vian kirjaaminen ei ole.

Zen Cartin oma lokihakemisto on logs/ kaupan juuressa, ja siellä ovat myös kaupan omat myDEBUG-*.log-tiedostot. Jos kauppa näyttää"WARNING: An Error occurred, please let us know!", vastaus on siellä.

13. Tekniset tiedot

Moduulin tiedostot

Tietokantataulut

Kaikki taulut luodaan kaupan omalla etuliitteellä.

Päivittäminen

Päivitys on tiedostojen kopiointi: kopioi paketin catalog/- hakemiston sisältö kaupan juureen.Moduulia ei tarvitse poistaa ja asentaa uudelleen — puuttuvat taulut ja puuttuvat asetukset luodaan itse. Se on tärkeää, koska poistaminen veisi mukanaan kauppiastunnuksen ja tarkisteavaimen.

Miksi sisääntulopisteet ovat ext/-hakemistossa

Paytrail palaa asiakkaan selaimella ja kutsuu kauppaa myös suoraan palvelimelta. Näitä osoitteita on useita, joten ne on koottu yhden hakemiston alle sen sijaan että ne olisi ripoteltu kaupan juureen. Ne eivät voi sijaita Zen Cart 2.x:n laajennushakemiston sisällä, koska sieltä tiedostoa ei tarjoilla — kauppa vastaa siihen 404.

Paytrail PSP -maksumoduuli Zen Cartille, versio 1.13.0 · AHCO Oy · Käyttöoikeudet laskussa.
Lisätiedot ja asennusohje: README.md ja INSTALL.md moduulin paketissa. Muutosloki: ChangeLogs.md.