Maksuturvan maksupalvelun äivitetty 4.6.2015
2 Maksuturvanmaksupalvelun Sisällysluettelo 1. Maksuturva-palveluiden kuvaus...4 1.1 Maksaminen...6 1.2 Toimitustietojen hallinta ja seuranta...8 1.3 Tyytyväisyystakuu...9 1.4 Sertifikaattisivu...15 2. Maksuturva-palveluiden käyttöprosessi...17 2.1 Maksaminen...18 2.2 Tilausten peruutukset ja muutokset...21 2.3 astaussanomien käsittely...23 3. Rajapintakuvaukset...24 3.1 Maksutapojen hakeminen (ostoskorikohtaisesti)...25 3.2 Dynaamisen kuva-aineiston hakeminen...27 3.2.1 Muutokset...28 3.2.2 Kuvien hakeminen...29 3.2.3 Maksutapabannerin linkittäminen palvelun sertifikaattisivuun...30 3.3 Maksaminen...31 3.3.1 Muutokset...33 3.3.2. Maksuviestin tiedot...37 3.3.2.1 Kenttien selitteet - Maksun välityksen tiedot...40 3.3.2.2 Tilauserittely...44 3.3.2.3 Tilauserittelyn laskentasäännöt...45 3.3.3 Maksuviestin vastauksen tiedot...46 3.3.3.1 astauksen tietojen tarkistaminen...47 3.3.3.2 Kenttien selitteet - Maksun vastaussanoman tiedot...48 3.4 Maksutapahtuman tilan kysely...50 3.4.1 Muutokset...51 3.4.2 Tapahtuman tilan kyselyn tiedot...53 3.4.2.1 Kenttien selitteet - Tapahtuman tilan kyselyn tiedot...54 3.4.3 Tapahtuman tilan kyselyn vastaussanoman tiedot...55 3.4.3.1 Kenttien selitteet - Tapahtuman tilan kyselyn vastaussanoman tiedot...56 3.4.3.1.1 astauskoodien arvot...59 3.4.3.1.2 Toimituksen tilakoodien arvot (vain Tyytyväisyystakuu-palveluille)...61 3.4.4. Maksutapahtuman tilan kyselyn erot eri käyttöympäristöissä...62 3.5 Toimitustietojen hallinta...63 3.5.1 Toimitustietojen välityksen tiedot...64 3.5.2 Toimitustietojen muokkauksen tiedot...65 3.5.3 Toimitustietojen poiston tiedot...66 3.5.4 Lähetystunnisteiden välityksen vastaussanoman tiedot...67 3.5.5 Kenttien selitteet...68 3.5.6 Toimitustapojen tunnisteet...69 3.5.7 astauskoodin arvot...71 3.6 alautusten ja peruutusten hallinta...72 3.6.1 Muutokset...73 3.6.2 Maksutapahtuman muutoksen tiedot...74 3.6.2.1 Kenttien selitteet - Maksun peruutuksen tiedot...76 3.6.3 Maksun peruutuksen vastaussanoman tiedot...78 3.6.3.1 Kenttien selitteet - Maksun peruutuksen vastaussanoman tiedot...79
Maksuturvanmaksupalvelun 3 3.7 Tilitysraporttien hakeminen...80 3.7.1 Muutokset...81 3.7.2 Raportin pyynnön tiedot...82 3.7.3 Tilitysraportin tiedot...83 3.7.3.1 Tilitysraportin tietojen looginen kuvaus...84 3.7.3.2 Tilitysraportin tarkiste...85 3.7.3.3 Tilitysraportin vastauksen XML...86 3.8 alvelun käyttöönotto (verkkokauppaohjelmistontarjoajille)...88 3.8.1 alvelun käyttöönoton tiedot...89 3.8.1.1 Kenttien selitteet - palvelun käyttöönoton tiedot...92 3.8.2 alvelun käyttöönoton vastaussanoman tiedot...95 3.8.2.1 Kenttien selitteet - alvelun käyttöönoton vastaussanoman tiedot...96 3.9 Tarkisteen laskenta...97 3.9.1 inkkejä tarkisteen laskennan avuksi...98 3.10 Maksuturva Erämaksun maksusuunnitelmien hakeminen...99 4. alvelun testaaminen...104 4.1 Sandbox-testaus...105 4.1.1 Rajapintakutsujen testauksen kuvaus yleisillä testitunnuksilla...107 4.2 Yksilölliset testitunnukset...108 4.2.1 erkkopankkien testitunnukset...109 4.2.2 Luotonmyöntäjien testitunnukset...111 5. Esimerkkejä...112 5.1 Maksutapojen hakeminen (ostoskorikohtaisesti)...113 5.2 Dynaamisen kuva-aineiston hakeminen...115 5.3 Maksaminen...116 5.3.1 Esimerkki maksusanoman koostamisesta ja tarkisteenlaskennasta (H)...121 5.4 Maksutapahtuman tilan kysely...125 5.5 Toimitustietojen hallinta...128 5.6 alautusten ja peruutusten hallinta...131 5.7 Tilitysraporttien hakeminen...134 6. FAQ...137 6.1. Mikä tämä virhe on?...138 6.1.1. existingayment (maksun tunnus ei kelpaa)...139 6.1.2. hash value is invalid...140
4 Maksuturvanmaksupalvelun 1. Maksuturva-palveluiden kuvaus Maksuturva on maksunvälityspalvelu verkkokaupoille. Tilaamalla ja integroimalla palvelun verkkokauppaan verkkokauppa saa asiakkaidensa käyttöön verkkopankkimaksut, korttimaksut sekä laskuilla ja erämaksuilla maksamisen maksutavat. Maksuturva vastaa maksujen veloittamisesta ostajalta, niiden tilittämisestä verkkokaupalle ja tilitysraporttien koostamisesta verkkokaupan kirjanpidon käyttöön. Suoramaksupalvelut (esim. emaksut) Yksinkertaisimmillaan Maksuturvaa on mahdollista käyttää suoramaksupalveluna (esimerkiksi emaksut), jossa ostajien maksut tilitetään verkkokaupalle päivittäin. erkkopankkimaksut tilittyvät verkkokaupalle näin yhdessä tai kahdessa pankkipäivässä. Maksuturvan palvelurajapinnoista verkkokaupalla on käytettävissä Maksutapojen hakeminen, Dynaamisen kuva-aineiston hakeminen, Maksaminen, Maksutapahtuman tilan kysely sekä Tilitysraporttien hakeminen. Tyytyväisyystakuu-palvelut (esim. Maksuturva Gold) Tyytyväisyystakuun sisältävissä niin sanotuissa escrow-palveluissa (esimerkiksi Maksuturva Gold) tilauksille määritellään tarkistusaika (suosituksena vähintään 14 päivää tilauksen vastaanottamisesta), jonka ajan Maksuturva säilyttää tilauksen maksua asiakasvaratilillään ja hallinnoi tilaukseen mahdollisesti tehtävien muutosten (esimerkiksi tuotepalautusten) vaikutuksia tilauksen loppusummiin. Tarkistusaika alkaa siitä, kun ostaja on vastaanottanut tilauksen, ja sen päätyttyä Maksuturva tilittää verkkokaupalle tilauksen loppusumman ja ostajalle mahdolliset palautettavat maksut. Maksuturvan palvelurajapinnoista verkkokaupalla on käytettävissä Maksutapojen hakeminen, Dynaamisen kuva-aineiston hakeminen, Maksaminen, Maksutapahtuman tilan kysely, Toimitustietojen hallinta, Tilauksen muuttaminen sekä Tilitysraporttien hakeminen. Tyytyväisyystakuun tuotepalautus- ym. palveluja ostaja pääsee käyttämään Maksuturvan erkko-ostajan palvelut -palvelusivulla. erkkokaupalle on käytössä KauppiasExtranet-palvelu. alvelurajapinnat lyhyesti
Maksuturvanmaksupalvelun 5
6 Maksuturvanmaksupalvelun 1.1 Maksaminen Oletusarvoisesti ostaja valitsee verkkokaupassa maksutavaksi Maksuturvan, minkä jälkeen verkkokauppaohjelmisto välittää tilauksen tiedot Maksuturvalle Maksaminen -rajapintaa käyttäen. Ostaja ohjataan Maksuturvan maksusivulle, jossa tämä valitsee haluamansa maksutavan verkkokaupan tarjoamista maksutapavaihtoehdoista. Maksusivun ulkoasu riippuu käytössä olevasta maksupalvelusta. Mikäli käytössä on suoramaksupalvelu (esimerkiksi emaksut), tulee maksusanomassa käyttää parametriä pmt_escrow=n ja vastaavasti Tyytyväisyystakuu-palvelussa pmt_escrow=y. Esimerkki: Ostaja maksaa tilauksen Aktia verkkomaksulla:
Maksuturvanmaksupalvelun Maksutavan valintasivun ohittaminen 7 Maksuturvan maksutavan valintasivu on mahdollista ohittaa, mikäli ostaja valitsee maksutavan jo verkkokaupassa. erkkokaupan Maksuturva-palvelussa käytössä olevat maksutavat tulee tällöin hakea tilauskorikohtaisesti käyttämällä Maksutapojen hakeminen -rajapintaa ja käyttää Maksaminen rajapinnan valinnaista parametria pmt_paymentmethod. Tyytyväisyystakuun sisältävien palveluiden tapauksessa maksusivun ohittaminen on mahdollista heti kun Maksuturva on sallinut ohituksen verkkokaupan palvelulla. Tämä johtuu siitä, että valitessaan maksutavan Maksuturvan maksusivulla, ostaja samalla hyväksyy sivulla esitellyt Maksuturvan Tyytyväisyystakuu-palvelun käyttöehdot. Jos maksutavan valintasivu ohitetaan Tyytyväisyystakuuta käyttävässä Maksuturva-palvelussa, on käyttöehdot tällöin esitettävä ja hyväksytettävä ostajalla verkkokaupan puolella. Esimerkki: Ostaja maksaa tilauksen Aktia verkkomaksulla (pmt_paymentmethod=fi03), jonka hän oli valinnut verkkokaupassa:
8 Maksuturvanmaksupalvelun 1.2 Toimitustietojen hallinta ja seuranta Toimitusten hallinta ja seuranta on käytössä vain Tyytyväisyystakuulla varustetuissa palveluissa. Toimitusten seuranta on saatavilla vain tilauksen koostuessa fyysisistä tuotteita eikä esimerkiksi ladattavista tuotteista tai palveluista. Kun tilaus on vahvistettu maksetuksi, verkkokauppa voi ilmoittaa tilauksen lähetetyksi tai toimitetuksi joko käyttämällä KauppiasExtranet-palvelua tai Toimitustietojen hallinta -rajapintaa. Ostaja voi seurata toimituksen etenemistä erkko-ostajan palveluissa. Tilauksen tuotteiden palautusaika eli tilauksen tarkistusaika käynnistyy vasta, kun Maksuturvan toimitusten seuranta -palvelu on saanut vahvistuksen, että ostaja on vastaanottanut kaikki tilaukseen ilmoitetut toimitukset. Näkymä erkko-ostajan palveluissa, kun tilaus on maksettu, mutta verkkokauppa ei ole vielä ilmoittanut tilauksen toimitustapatietoja. Näkymä erkko-ostajan palveluissa, kun tilauksen toimitustapatiedot on toimitettu. Näkymä erkko-ostajan palveluissa, kun tilauksen toimitus on vastaanotettu tai noudettu.
Maksuturvanmaksupalvelun 1.3 Tyytyväisyystakuu 9 erkkokauppa valitsee tilausten tarkistusajan pituuden Maksuturva-palvelun tilaamisen yhteydessä. Tarkistusaikaa voidaan myös muuttaa joustavasti tämän jälkeenkin. Tilauskohtaisen tarkistusajan laskentaa alkaa, kun kaikki tilaukseen liittyvät toimitukset on vahvistettu vastaanotetuiksi. Tilaukseen on mahdollista esittää muutoksia ennen tarkistusajan alkamista tai sen aikana. Ostajan tekemät muutosesitykset edellyttävät aina verkkokaupan vahvistuksen. erkkokaupan tekemät muutosesitykset vahvistetaan automaattisesti ja niitä vastaavat maksut tilitetään välittömästi, mikäli mahdollista. Tästä poikkeuksena verkkopankissa maksetut tilaukset, joihin liittyvien maksupalautusten tilitykset edellyttävät ostajalta tilinumeroa, jonne ostajalle palautettava rahamäärä palautetaan. Näitä toimintoja varten ostajalla on käytössään Maksuturvan erkko-ostajan palvelut. erkkokauppa voi esittää muutoksia tilaukseen käyttämällä KauppiasExtranet-palvelua tai Maksutapahtuman muuttaminen -rajapintaa. Ostajan tekemät muutosehdotukset tai reklamaatiot tilaukselle jäädyttävät aina tilauksen rahaliikenteen kunnes osapuolet sopivat ratkaisusta - eli muutosehdotus vahvistetaan tai ehdotuksen tekijä peruuttaa ehdotuksensa. erutun muutosehdotuksen tai reklamaation tilalle voi tehdä uuden ehdotuksen. Mikäli peruminen tehdään tarkistusajan päätyttyä, tilauksen maksut tilitetään osapuolille heti seuraavana pankkipäivänä. Jos muutosehdotus siis halutaan perua ja korvata uudella muutosehdotuksella tarkistusajan päätyttyä, on uusi ehdotus tehtävä saman vuorokauden aikana.
10 Maksuturvanmaksupalvelun Tarkistusajan päätyttyä Maksuturva tilittää tilauksen summan verkkokaupalle ja palauttaa tai hyvittää mahdollisen muutoksen mukaisen rahamäärän ostajalle.
Maksuturvanmaksupalvelun Esimerkkejä Tyytyväisyystakuun toiminnoista erkko-ostajan palveluissa Yksittäisten tuotteiden palautus- ja peruutuslomake 11
12 Maksuturvanmaksupalvelun Koko tilauksen palautus- ja peruutuslomake Hinnanalennuksen esittämisen lomake
Maksuturvanmaksupalvelun 13 Reklamaatiolomake. Ostajan tekemästä reklamaatiosta lähetetään viesti verkkokaupalle. Reklamaatiolomakkeella ostaja voi ilmoittaa verkkokaupalle puutteista tai virheistä tilauksessa tarvitsematta vielä esittää rahallista hyvitystä tai muuta muutosta asian ratkaisemiseksi - varmistaen kuitenkin, ettei tilauksen maksu tility verkkokaupalle ennen ongelman ratkaisemista. Reklamaation käyttäminen mahdollistaa myös osapuolten sopia muista kuin hintaa alentavista ratkaisuista - esimerkiksi korvaavan tuotteen toimittamisesta viallisen tilalle.
14 Maksuturvanmaksupalvelun Tilauksen tietojen erittely erkkoostajan palveluissa tilauksen muutosten vahvistuksen jälkeen.
Maksuturvanmaksupalvelun 1.4 Sertifikaattisivu 15 Maksuturvan Tyytyväisyystakuun sisältäviin palveluihin sisältyy myös palvelukohtainen sertifikaattisivu, jonka verkkokauppa voi linkittää sivuilleen. Suosituksena on linkin sijoittaminen Maksuturvan maksutapabannerin ympärille. Sertifikaattisivulla esitellään verkkokaupan keskeiset tiedot, maksutavat, tuotepalautusten ehdot ja Tyytyväisyystakuun toiminnot.
16 Maksuturvanmaksupalvelun Esimerkki sertifikaattisivusta
Maksuturvanmaksupalvelun 2. Maksuturva-palveluiden käyttöprosessi 17
18 Maksuturvanmaksupalvelun 2.1 Maksaminen Molemmissa, sekä Maksuturvan suoramaksu- (esim. emaksut) että Tyytyväisyystakuu-palveluissa (esim. Maksuturva Gold), maksamisen yhteydessä käytetään Maksaminen -rajapintaa. Kun ostaja on suorittanut maksun verkkopankissa, kortilta tai vahvistanut laskutussopimuksen, Maksuturva lähettää verkkokaupalle vastaussanoman maksuviestissä annettuun vastausosoitteeseen. astaussanoma lähtee myös, jos maksaminen peruuntuu ostajan keskeyttämänä tai palvelussa ilmenneeseen virhetilanteeseen. Kullekin lopputulokselle (ok, cancel, error) on syytä määritellä oma paluuosoitteensa.
Maksuturvanmaksupalvelun 19
20 Maksuturvanmaksupalvelun Maksutapahtuman tilan kysely On myös mahdollista, ettei verkkokauppa vastaanota maksamisen vastausviestiä. Tällaisia tilauksia ei tulisi koskaan tulkita verkkokaupassa asiakkaan tarkoituksella keskeyttämiksi, sillä vastauksen puuttuminen saattaa johtua myös ostajan verkkoyhteyden katkeamisesta tai internetselaimen sulkemisesta kesken maksutapahtuman. Kaikki verkkokaupan tilaukset, joihin verkkokauppa ei ole saanut OK--vastausta, tulee varmistaa Maksuturvalta Maksutapahtuman tilan kyselyn rajapintaa käyttäen. Maksuturva varmistaa tarvittaessa maksutoimeksiannon tilan pankista, korttimaksujen käsittelijältä tai luotonmyöntäjältä. alveluiden eroista johtuen sen, että tilauksen maksu on tosiasiallisesti suoritettu tai keskeytetty, voi luotettavimmin todeta, kun tilauksen tekemisestä ja viimeisestä ostajan toimesta ko. maksutapahtumaan liittyen on kulunut vähintään tunti. Katso tarkempi ohjeistus Maksutapahtuman tilan kysely -rajapinnan kuvauksesta.
Maksuturvanmaksupalvelun 2.2 Tilausten peruutukset ja muutokset Alla joitakin esimerkkejä peruutus- ja palautusprosesseista. 21
22 Maksuturvanmaksupalvelun
Maksuturvanmaksupalvelun 2.3 astaussanomien käsittely 23 erkkokaupan Maksuturvalle ja Maksuturvan takaisin verkkokaupalle välitettävien tietojen osalta on ehdottomasti tarkistettava tietojen muuttumattomuus. Tällä tarkoitetaan sitä, että kaikkien tarkisteen (hash) sisältämien pyyntöjen ja vastaussanomien tiedoista on aina laskettava tarkiste ja verrattava sitä pyynnössä tai vastauksessa olevaan tarkisteeseen. Tarkemmat kuvaukset lähtevien ja vastausviestien tarkisteiden laskemisesta löytyvät rajapintakuvauksista ja tarkisteen laskennan ohjeista. Maksuturvan välittämät erilliset vastaustiedot on lisäksi tarkistettava muodollisesti, rajapintakuvauksen mukaan. Jos kaikki yllä olevat vaiheet menevät onnistuneesti läpi (tarkisteet täsmäävät ja tiedot ovat muodollisesti valideja), voidaan sanoman katsoa olevan validi ja se voidaan käsitellä asianmukaisesti.
24 Maksuturvanmaksupalvelun 3. Rajapintakuvaukset Kaikki Maksuturvan tuotantoympäristön palveluiden kutsut suoritetaan salattua HTTStiedonsiirtoprotokollaa käyttäen, esimerkiksi https://www.maksuturva.fi/newaymentextended.pmt. Salattu yhteys suojelee palvelukutsujen tietojen näkymistä ulkopuolisille ja varmentaa käyttäjälle, että yhteys on muodostettu nimenomaan aitoon Maksuturvan palveluun. Testattaessa Maksuturvan palveluita Maksuturvan testiympäristössä käytetään salaamatonta HTTtiedonsiirtoprotokollaa, esimerkiksi: http://test1.maksuturva.fi/newaymentextended.pmt. Lue lisää kohdasta testaaminen. Kaikille Maksuturvan rajapinnoille yhteinen parametri on verkkokaupan tunnus (eli "kauppiastunnus" tai "palvelun teknisen rajapinnan tunnus") pmt_sellerid, joka kertoo Maksuturvan palvelulle, minkä verkkokaupan palvelukutsusta on kyse. arametrin avulla maksu kohdistetaan oikean verkkokaupan tilaukseksi, maksubanneria ladattaessa palautetaan vastauksena juuri kyseisen palvelun maksutapojen kuvat ja sertifikaattisivun kohdalla näytetään juuri kyseisen palvelun tiedot. erkkokaupan tunnus ei ole salainen tieto, vaan sitä käytetään julkisena parametrina esimerkiksi verkkokauppojen sertifikaattisivuilla: https://www.maksuturva.fi/certificate.pmt? seller_id={erkkokauan_tunnus]&request_locale=fi. iestien aitous varmistetaan muodostamalla kunkin rajapintakutsun viestin ja vastaussanoman (rajapintakuvauksessa määritellyistä) kentistä merkkijono, lisäämällä sen loppuun verkkokaupan salainen avain ja laskemalla uudesta merkkijonosta tarkiste. erkkokaupan tulee pitää salainen avain salassa ulkopuolisilta eikä avainta itseään pidä koskaan lähettää viestien mukana. Kun Maksuturva vastaanottaa viestin verkkokaupalta tai verkkokauppa vastausviestin Maksuturvalta, vastaanottaja laskee vastaanottamastaan viestistä ja tiedossaan olevasta salaisesta avaimesta tarkisteen ja varmistaa, että se on yhtenevä vastaanotetun viestin mukana tulleen tarkisteen kanssa. Kun tarkisteet vastaavat toisiaan, voi vastaanottaja kohtuullisella varmuudella luottaa lähettäjän aitouteen. Koska palvelun salainen avain on mahdollista päivittää, tarkistetta käyttävien viestien mukana kulkee myös tieto salaisen avaimen sukupolvesta (eli versiosta), pmt_keygeneration. arametri kertoo, monesko verkkokaupalle kytketty salainen avain on käytössä. alvelun käytön alussa versionumero on 001. Rajapintakohtaiset kutsuviestien ja vastaussanomien parametrit eritellään tarkemmin kussakin rajapintakuvauksessa.
Maksuturvanmaksupalvelun 25 3.1 Maksutapojen hakeminen (ostoskorikohtaisesti) Mikäli ostaja valitsee maksutavan jo verkkokaupan puolella, ostajan valittavissa olevat maksutavat tulee hakea joka kerta, kun ostajalle halutaan näyttää maksutavat tilauksen maksamista varten. Tämä on usein välttämätöntä, sillä joillakin maksutavoilla on vaatimuksia tilauksen loppusumman osalta (minimi- ja maksimirahamäärät). Tämän vuoksi maksutapojen hakupyynnössä on mukana tieto totalamount, jonka perusteella Maksuturva palauttaa verkkokaupalle ko. tilauksen tapauksessa ostajan valittavissa olevat maksutavat. Eli toisin sanoen pienillä (esim. alle 70 ) tai suurilla (esim. yli 1000 ) tilauksen loppusummien tapauksessa vain osa maksutavoista on saatavilla ko. tilauksen maksamista varten. Tällä hetkellä ainoastaan pankki- ja korttimaksut ovat aina valittavissa tilauksen loppusummasta riippumatta. Mikäli verkkokaupalla on käytössään nettotilitykset (oletusarvo), kunkin tilauksen loppusumman on toki ylitettävä transaktiomaksun minimi (esim. yleensä 0,50 korttimaksuilla). Tämä ei koske verkkokauppoja, joilla on käytössään bruttotilitykset, jossa transaktiomaksut veloitetaan jälkikäteen laskulla. Maksutavat saa haettua sekä GET- että OST-metodilla osoitteesta https://www.maksuturva.fi/ GetaymentMethods.pmt (tai http://test1.maksuturva.fi/getaymentmethods.pmt testiympäristössä). astauksessa (XML) ilmeneviä maksutapakoodeja (<code>) käytetään Maksaminen -rajapinnan parametrin pmt_paymentmethod arvona. Hakusanoman tiedot Kentän Kenttä numero Tiedon nimi Arvo input name= value= 1. erkkokaupan tekninen tunnus sellerid 2. Kieli, jolla maksutapojen nimet halutaan request_locale fi, sv, en Muoto Minimipituus / AN50 4 A2 2 AN17 4 oletus: fi 3. Tilauksen loppusumma, jota tullaan totalamount esim. 47,50 maksamaan, sisältäen kaikki kulut. astaussanomat tiedot astaussanoma (XML-dokumentti) palautetaan vastauksena HTT GET/OST-pyyntöön. XML-sisältö selviää parhaiten alla olevasta esimerkistä. Esimerkki pyynnöstä (GET): https://www.maksuturva.fi/getaymentmethods.pmt? sellerid=sellerid&request_locale=fi&totalamount=47,50 Esimerkki vastauksesta:
26 Maksuturvanmaksupalvelun <?xml version="1.0" encoding="iso-8859-1" standalone="no"?> <paymentmethods> <paymentmethod> <code>fi01</code> <displayname>nordea E-maksu</displayname> </paymentmethod> <paymentmethod> <code>fi06</code> <displayname>osuuspankki erkkomaksu</displayname> </paymentmethod> </paymentmethods> Materiaalit verkkokauppaan Maksutapojen logot yms. ovat saatavilla kotisivuiltamme: https://www.maksuturva.fi/fi/ohjeet/materiaalipankki/materiaalit-verkkokauppaan/ verkkomaksupainikkeet/
Maksuturvanmaksupalvelun 3.2 Dynaamisen kuva-aineiston hakeminen 27 Dynaamisten kuva-aineistojen hakemisen rajapintakuvaus, versio 1.1 Tämä rajapinta mahdollistaa verkkokaupan Maksuturvan palveluihin kytkettyjen dynaamisten kuvaaineistojen hakemisen käyttämällä verkkokaupan teknistä tunnusta. astauksena tulevan NG-kuvan sisältö riippuu käytössä olevan palvelun ominaisuuksista. Esimerkkejä rajapinnan palauttamista kuvista: bannertype=logo (kun käytössä Maksuturva-palvelu) bannertype=logo (kun käytössä emaksut-palvelu) bannertype=payment_methods_horizontal&rowscolumns=2&request_locale=en (kun käytössä Maksuturva-palvelu)
28 Maksuturvanmaksupalvelun 3.2.1 Muutokset Ajankohta Dokumentin Muutos versio Elokuu 1.0 2014 Dynaamisen kuva-aineiston rajapintakuvaus omana rajapintakuvauksenaan. Uusina ominaisuuksina maksutapabannerin koon valinta ja käytössä olevan maksunvälityspalvelun logon noutaminen. Toukokuu 1.1 äivitetty kuvaesimerkkejä vastaamaan nykyisiä palvelupaketteja 2015
Maksuturvanmaksupalvelun 29 3.2.2 Kuvien hakeminen erkkokauppakohtainen käytetyn maksupalvelun logo sekä maksutapabannerit ovat haettavissa NGkuvana osoitteesta https://www.maksuturva.fi/banner.pmt (tai http://test1.maksuturva.fi/banner.pmt testiympäristössä). Banneria ei muodosteta kokonaan dynaamisesti, vaan siitä on tehty erilaisia versioita, joista valitaan sopivin verkkokaupan palvelun ja palvelukutsun parametrien perusteella. Banner.pmt -rajapintaan viittaava linkki liitetään kaupan HTML-sivulle img-tagina. yyntö Kentän Kenttä numero 1. erkkokaupan Tiedon nimi Arvo input name= value= sellerid Muoto Minimipituus / AN50 4 tekninen tunnus 2. Bannerin tyyppi bannertype logo A50 payment_methods_vertical payment_methods_horizontal 3. Kielikoodi request_locale fi, en, sv. Oletus: fi A2 2 4. Bannerin koko rowscolumns horizontal: 2 6, N2 1 riveinä tai vertical: 2 20 palstoina Oletus: 3 astaus on redirect (HTT 302) NG-muotoiseen kuvaan. Esimerkiksi: <img src="https://www.maksuturva.fi/banner.pmt?sellerid=sellerid&bannertype=logo " /> tai <img src="https://www.maksuturva.fi/banner.pmt? sellerid=sellerid&bannertype=payment_methods_vertical&request_locale=sv" />
30 Maksuturvanmaksupalvelun 3.2.3 Maksutapabannerin linkittäminen palvelun sertifikaattisivuun Maksuturva-palveluissa verkkokaupalle on tarjolla sertifikaattisivu, jolla esitellään kuluttajalle verkkokaupan keskeiset maksamista ja palautuksia koskevat ehdot ja ohjeet. Maksutapabanneri suositellaankin aina esitettävän verkkokaupan sivuilla linkitettynä palvelun sertifikaattisivuun. Sertifikaattisivun linkki muodostetaan seuraavasti: Kentän Kenttä numero 1. erkkokaupan tekninen Tiedon nimi Arvo input name= value= sellerid request_locale fi, en, sv. Oletus: fi Muoto Minimipituus / AN50 4 A2 2 tunnus 2. Kielikoodi Esimerkiksi: <a href="https://www.maksuturva.fi/certificate.pmt?seller_id=sellerid&request_locale=fi" target="_blank" title="lue lisää Tyytyväisyystakuusta"> <img src=https://www.maksuturva.fi/banner.pmt? sellerid=sellerid&bannertype=payment_methods_horizontal&request_locale=fi&rowscolumns=2 /> </a>
Maksuturvanmaksupalvelun 31 3.3 Maksaminen Maksuturvan Maksurajapinnan kuvaus, versio 4.1.13 Tämän rajapinnan kautta verkkokauppa toimittaa tilauksen eli maksutoimeksiannon tiedot Maksuturvalle, minkä jälkeen ostaja valitsee maksutavan ja maksaa tilauksen tai vaihtoehtoisesti keskeyttää maksamisen omasta tahdostaan. aluuosoitteet Ostaja/tilaaja maksaa valitsemallaan maksutavalla ja maksamisen onnistuminen käy ilmi lähes aina siitä, mihin verkkokaupan ilmoittamaan paluusoitteeseen vastaussanoma ohjautuu: ok-paluuosoite (pmt_okreturn): maksu on maksettu peruutus -paluuosoite (pmt_cancelreturn): maksaminen keskeytyi (ostaja todennäköisesti yksinkertaisesti päätti olla maksamatta) virhe -paluuosoite (pmt_errorreturn): maksaminen keskeytyi virheeseen viivästetty maksu -paluuosoite (pmt_delayedpayreturn): maksaja vahvisti toimeksiannon ja aikoo maksaa tilisiirrolla (maksua ei ole vielä rekisteröity). HUOM! Tilisiirtoa ei tueta enää nykyisissä valmispaketeissa. Siksi usein ehdotammekin käytettävän viivästetty maksupaluuosoitteeseena samaa osoitetta kuin peruutusten tapauksessa (pmt_delayedpayreturn ~= pmt_cancelreturn). Joissakin poikkeustilanteissa ostaja ei onnistu palaamaan verkkokauppaan. Tästä syystä verkkokaupan on ehdottoman välttämätöntä käyttää Maksaminen -rajapinnan lisäksi myös Maksutapahtuman tilan kysely -rajapintaa. Katso tarkemmat ohjeet ko. rajapinnan kuvauksesta. Escrow-parametri Huomaathan, että pmt_escrow-parametrin arvo määrittää käytetyn palvelun (väärä arvo ei kelpaa, vaan siitä seuraa tekninen virhe): Tyytyväisyystakuu-palvelu: pmt_escrow=y Suoramaksupalvelu: pmt_escrow=n Maksutavan valinta verkkokaupan puolella Maksuturvan maksutavan valintasivu on mahdollista ohittaa, mikäli ostaja valitsee maksutavan jo verkkokaupassa. erkkokaupan tulee tällöin hakea valittavissa olevat maksutavat tilauskohtaisesti käyttämällä Maksutapojen hakeminen -rajapintaa. erkkokauppa välittää valitun maksutavan Maksaminen -rajapinnan valinnaisen parametrin pmt_paymentmethod arvona. Maksutavan valintasivun ohittamisen ominaisuus on aina aktivoitava erikseen Maksuturvan puolella, muutoin se ei yleensä toimi. Maksutavan valintasivulla ostaja samalla hyväksyy sivulla esitellyt Maksuturvan Tyytyväisyystakuupalvelun käyttöehdot. Jos maksutavan valintasivu ohitetaan Tyytyväisyystakuuta käyttävässä verkkokaupassa, on em. käyttöehdot tällöin esiteltävä ja hyväksytettävä ostajalla verkkokaupan puolella tilausta tehtäessä. alittaessa Maksuturvan maksutavan valintasivun ohituksen ostajan sähköpostiosoite on pakollinen parametri. Sen puuttuminen aiheuttaa virheen, joka palauttaa ostajan takaisin verkkokauppaan. Tilauksen vastaanottajan osoite
32 Maksuturvanmaksupalvelun Tilauksen vastaanottajan osoitteen (pmt_deliveryaddress jne.) tulee aina vastata osoitetta, johon tilaus tosiasiallisesti lähetetään. Jos esimerkiksi tilaaja antaa laskutusosoitteeksi (pmt_buyeraddress jne.) kotiosoitteensa, mutta valitsee lähetyksen noudettavaksi myymälästä tai pakettiautomaatista, tulee tilauksen toimitusosoitteina antaa myymälän tai pakettiautomaatin osoite.
Maksuturvanmaksupalvelun 3.3.1 Muutokset Ajankohta Dokumentin Muutos versio Marraskuu 2.5 aluusanoman kuvaukseen lisätty pmt_paymentmethod -kentän kuvaus. 4.0 Uusi rajapintaversio: 0004 2010 Helmikuu 2011 MAKSUN ÄLITYKSEN TIEDOT (IN): alinnaiset tiedot pakolliseksi: pakolliseksi maksun eräpäivä (pmt_duedate) pakolliseksi virhe-paluuosoite (pmt_errorreturn) pakolliseksi vastaanottajan nimi (pmt_deliveryname) pakolliseksi vastaanottajan osoite (pmt_deliveryaddress) pakolliseksi vastaanottajan postinumero (pmt_deliverypostalcode) pakolliseksi tarkisteen laskentamerkistö (pmt_charset) Uusi pakollinen tieto: pmt_action (NEW_AYMENT_EXTENDED) sisään tulevan datan ja verkkokaupan enkoodaus (pmt_charsethttp) Tuki maksutavan esivalinnalle verkkokaupassa: erkkokaupassa esivalittu maksutapa (pmt_paymentmethod) Tulevien ominaisuuksien tueksi: pakollinen escrow käytössä (pmt_escrow) pakollinen escrow valittavissa (pmt_escrowchangeallowed) Kansainvälisten (luottokortti)maksujen tueksi: pakollinen maksajan kaupunki (pmt_buyercity) pakollinen maksajan maakoodi (pmt_buyercountry) pakollinen toimituksen kaupunki (pmt_deliverycity) pakollinen toimituksen maakoodi (pmt_deliverycountry) Erilaisten rahalaitosten myöntämien luottojen mahdollistamiseksi: valinnainen parametri, joka kertoo lähettääkö kauppias laskun (pmt_invoicefromseller) valinnainen ostajan hetu tai y-tunnus (pmt_buyeridentificationcode) pakollinen tilauserittely: Tilausrivien lukumäärä (pmt_rows) Tilausrivin tuotteen nimi (pmt_row_namen) Tilausrivin tuotteen kuvaus (pmt_row_descn) Tilausrivin tuotteen määrä (pmt_row_quantityn) Tilausrivin toimituksen tai palvelun suorituksen ajankohta (pmt_row_deliverydaten) Tilausrivin tuotteen bruttohinta per yksikkö (AL mukana) (pmt_row_price_grossn) Tilausrivin tuotteen nettohinta per yksikkö (ilman AL:a) (pmt_row_price_netn) Tilausrivin tuotteeseen sovellettu AL-prosentti (pmt_row_vatn) Tilausrivin tyyppi (pmt_row_typen) 33
34 Maksuturvanmaksupalvelun akollinen myyjän tai toimittajan käsittely- ja postikulu: pmt_sellercosts Uusi tarkiste: pmt_action pmt_version pmt_selleriban (vain jos annettu) pmt_id pmt_orderid pmt_reference pmt_duedate pmt_amount pmt_currency pmt_okreturn pmt_errorreturn pmt_cancelreturn pmt_delayedpayreturn pmt_escrow pmt_escrowchangeallowed pmt_invoicefromseller (vain jos annettu) pmt_paymentmethod (vain jos annettu) pmt_buyeridentificationcode (vain jos annettu) pmt_buyername pmt_buyeraddress pmt_buyerpostalcode pmt_buyercity pmt_buyercountry pmt_deliveryname pmt_deliveryaddress pmt_deliverypostalcode pmt_deliverycity pmt_deliverycountry pmt_sellercosts pmt_row_* kentät järjestyksessä riveittäin tilausrivi kerrallaan kaikki seuraavat (jos mukana tiedoissa): pmt_row_namen pmt_row_descn pmt_row_quantityn pmt_row_articlenrn pmt_row_unitn pmt_row_deliverydaten pmt_row_price_grossn pmt_row_price_netn pmt_row_vatn pmt_row_discountpercentagen pmt_row_typen <salainen avain> MAKSUN ASTAUSSANOMAN TIEDOT (OUT) alittu maksutapa (pmt_paymentmethod) uudet koodit ja selitteet: FI70 - Maksuturva-Lasku (luotto- ja rahoituspalvelu) FI71 - Maksuturva-Osamaksu (luotto- ja rahoituspalvelu) FI80 - Maksuturva-aypal
Maksuturvanmaksupalvelun FI90 - Maksuturva-K-tilisiirto Tulevien ominaisuuksien tueksi: (pmt_escrow) Uusi kenttä: pmt_action (NEW_AYMENT_EXTENDED) Uusia kenttiä tarkisteessa: pmt_action (NEW_AYMENT_EXTENDED) pmt_version Toukokuu 4.1 2011 MAKSUN ÄLITYKSEN TIEDOT (IN): Uusia valinnaisia tietoja: pmt_row_articlenrn tilausrivin tuotteen tuotenumero verkkokaupassa pmt_row_unitn tilausrivin määrän yksikkö (esim. kg, kpl) Yllä olevat tiedot lisätty myös tarkisteenlaskentaan. Syyskuu 4.1.1 2011 Lisätty lisätiedot emaksujen integrointiin ohje sallittujen maksutapojen hakemiseen ohje maksubannerin hakemiseen. Joulukuu 4.1.2 2011 Maaliskuu Lisätty lisäohjeita hash-laskentaan 4.1.4 idennetty maksajan ja toimitustietojen nimi- ja osoitekenttiä. 4.1.5 Ei muutoksia 4.1.6 Lisätty uudet maksutavat: 2013 Kesäkuu 2013 Huhtikuu 2014 Toukokuu Maksuturva Lasku Maksuturva Erämaksu 4.1.7 2014 Heinäkuu Lisätty sallittujen maksutapojen hakuun uusi parametri: totalamount (tilauksen loppusumma) 4.1.8 Lisätty huomautus toimitusosoitteen paikkansapitävyyden tärkeydestä 4.1.9 Korvattu maksutapabannerin haun rajapintakuvaus viittauksella omaan dokumenttiinsa 4.1.10 Nimetty uudelleen Aktian, Säästöpankin ja O ankin maksutavat. 4.1.11 Lisätty vastaussanoman kuvaukseen, että pmt_sellercosts -muuttujan arvo nousee vastaussanomassa, 2014 Elokuu 2014 Syyskuu 2014 Lokakuu 2014 Huhtikuu 2015 jos valitussa maksutavassa on käytössä laskutuslisä 4.1.12 Lisätty uudet maksutavat: Yrityslasku 35