lataa Maksuturvan maksupalvelun integrointiohjeet pdf
Transcription
lataa Maksuturvan maksupalvelun integrointiohjeet pdf
Maksuturvan maksupalvelun integrointiohjeet Päivitetty 26.2.2015 2 / 129 Maksuturvan maksupalvelun integrointiohjeet 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 Vastaussanomien käsittely ......................................................................................................23 3. Rajapintakuvaukset .........................................................................................................................24 3.1 Maksutapojen hakeminen (ostoskorikohtaisesti).....................................................................25 3.2 Dynaamisen kuva-aineiston hakeminen .................................................................................27 3.2.1 Muutokset .......................................................................................................................29 3.2.2 Kuvien hakeminen ..........................................................................................................30 3.2.3 Maksutapabannerin linkittäminen palvelun sertifikaattisivuun ........................................31 3.3 Maksaminen ............................................................................................................................32 3.3.1 Muutokset .......................................................................................................................33 3.3.2. Maksuviestin tiedot ........................................................................................................36 3.3.2.1 Kenttien selitteet - Maksun välityksen tiedot .........................................................39 3.3.2.2 Tilauserittely ...........................................................................................................43 3.3.2.3 Tilauserittelyn laskentasäännöt .............................................................................44 3.3.3 Maksuviestin vastauksen tiedot .....................................................................................45 3.3.3.1 Vastauksen tietojen tarkistaminen .........................................................................46 3.3.3.2 Kenttien selitteet - Maksun vastaussanoman tiedot ..............................................47 3.4 Maksutapahtuman tilan kysely ................................................................................................49 3.4.1 Muutokset .......................................................................................................................50 3.4.2 Tapahtuman tilan kyselyn tiedot .....................................................................................52 3.4.2.1 Kenttien selitteet - Tapahtuman tilan kyselyn tiedot ..............................................53 3.4.3 Tapahtuman tilan kyselyn vastaussanoman tiedot .........................................................54 3.4.3.1 Kenttien selitteet - Tapahtuman tilan kyselyn vastaussanoman tiedot ..................55 3.4.3.1.1 Vastauskoodien arvot ...................................................................................57 3.4.3.1.2 Toimituksen tilakoodien arvot (vain Tyytyväisyystakuu-palveluille) ..............59 3.5 Toimitustietojen hallinta ...........................................................................................................60 3.5.1 Toimitustietojen välityksen tiedot ....................................................................................61 3.5.2 Toimitustietojen muokkauksen tiedot .............................................................................62 3.5.3 Toimitustietojen poiston tiedot ........................................................................................63 3.5.4 Lähetystunnisteiden välityksen vastaussanoman tiedot.................................................64 3.5.5 Kenttien selitteet .............................................................................................................65 3.5.6 Toimitustapojen tunnisteet ..............................................................................................66 3.5.7 Vastauskoodin arvot .......................................................................................................68 3.6 Palautusten ja peruutusten hallinta .........................................................................................69 3.6.1 Muutokset .......................................................................................................................70 3.6.2 Maksutapahtuman muutoksen tiedot .............................................................................71 3.6.2.1 Kenttien selitteet - Maksun peruutuksen tiedot .....................................................73 3.6.3 Maksun peruutuksen vastaussanoman tiedot ................................................................75 3.6.3.1 Kenttien selitteet - Maksun peruutuksen vastaussanoman tiedot .........................76 3.7 Tilitysraporttien hakeminen......................................................................................................77 Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 3 / 129 3.7.1 Muutokset .......................................................................................................................78 3.7.2 Raportin pyynnön tiedot .................................................................................................79 3.7.3 Tilitysraportin tiedot ........................................................................................................80 3.7.3.1 Tilitysraportin tietojen looginen kuvaus .................................................................81 3.7.3.2 Tilitysraportin tarkiste.............................................................................................82 3.7.3.3 Tilitysraportin vastauksen XML .............................................................................83 3.8 Palvelun käyttöönotto (verkkokauppaohjelmistontarjoajille) ....................................................85 3.8.1 Palvelun käyttöönoton tiedot ..........................................................................................86 3.8.1.1 Kenttien selitteet - palvelun käyttöönoton tiedot ...................................................89 3.8.2 Palvelun käyttöönoton vastaussanoman tiedot ..............................................................92 3.8.2.1 Kenttien selitteet - Palvelun käyttöönoton vastaussanoman tiedot .......................93 3.9 Tarkisteen laskenta ..................................................................................................................94 3.9.1 Vinkkejä tarkisteen laskennan avuksi ............................................................................95 4. Palvelun testaaminen ......................................................................................................................96 4.1 Sandbox-testaus ....................................................................................................................97 4.1.1 Vinkkejä virheiden paikallistamiseen ..............................................................................99 4.1.2 Rajapintakutsujen testauksen kuvaus yleisillä testitunnuksilla .....................................100 4.2 Yksilölliset testitunnukset ......................................................................................................101 4.2.1 Verkkopankkien testitunnukset .....................................................................................102 4.2.2 Luotonmyöntäjien testitunnukset ..................................................................................104 5. Esimerkkejä ...................................................................................................................................105 5.1 Maksutapojen hakeminen (ostoskorikohtaisesti)...................................................................106 5.2 Dynaamisen kuva-aineiston hakeminen ...............................................................................108 5.3 Maksaminen ..........................................................................................................................109 5.3.1 Esimerkki maksusanoman koostamisesta ja tarkisteenlaskennasta (PHP) .................114 5.4 Maksutapahtuman tilan kysely ..............................................................................................118 5.5 Toimitustietojen hallinta .........................................................................................................121 5.6 Maksutapahtuman muuttaminen ...........................................................................................124 5.7 Tilitysraporttien hakeminen ....................................................................................................127 Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 4 / 129 Maksuturvan maksupalvelun integrointiohjeet 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. Verkkopankkimaksut 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 Verkko-ostajan palvelut -palvelusivulla. Verkkokaupalle on käytössä KauppiasExtranet-palvelu. Palvelurajapinnat lyhyesti Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 5 / 129 6 / 129 Maksuturvan maksupalvelun integrointiohjeet 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: Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet Maksutavan valintasivun ohittaminen 7 / 129 Maksuturvan maksutavan valintasivu on mahdollista ohittaa, mikäli ostaja valitsee maksutavan jo verkkokaupassa. Verkkokaupan 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: Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 8 / 129 Maksuturvan maksupalvelun integrointiohjeet 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ä Verkko-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ä Verkko-ostajan palveluissa, kun tilaus on maksettu, mutta verkkokauppa ei ole vielä ilmoittanut tilauksen toimitustapatietoja. Näkymä Verkko-ostajan palveluissa, kun tilauksen toimitustapatiedot on toimitettu. Näkymä Verkko-ostajan palveluissa, kun tilauksen toimitus on vastaanotettu tai noudettu. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 1.3 Tyytyväisyystakuu 9 / 129 Verkkokauppa 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. Verkkokaupan 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 Verkko-ostajan palvelut. Verkkokauppa 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. Perutun 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. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 10 / 129 Maksuturvan maksupalvelun integrointiohjeet Tarkistusajan päätyttyä Maksuturva tilittää tilauksen summan verkkokaupalle ja palauttaa tai hyvittää mahdollisen muutoksen mukaisen rahamäärän ostajalle. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet Esimerkkejä Tyytyväisyystakuun toiminnoista Verkko-ostajan palveluissa Yksittäisten tuotteiden palautus- ja peruutuslomake Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 11 / 129 12 / 129 Maksuturvan maksupalvelun integrointiohjeet Koko tilauksen palautus- ja peruutuslomake Hinnanalennuksen esittämisen lomake Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 13 / 129 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. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 14 / 129 Maksuturvan maksupalvelun integrointiohjeet Tilauksen tietojen erittely Verkkoostajan palveluissa tilauksen muutosten vahvistuksen jälkeen. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 1.4 Sertifikaattisivu 15 / 129 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. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 16 / 129 Maksuturvan maksupalvelun integrointiohjeet Esimerkki sertifikaattisivusta Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 2. Maksuturva-palveluiden käyttöprosessi Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 17 / 129 18 / 129 Maksuturvan maksupalvelun integrointiohjeet 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. Vastaussanoma 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. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 19 / 129 20 / 129 Maksuturvan maksupalvelun integrointiohjeet 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ä. Palveluiden 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. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 2.2 Tilausten peruutukset ja muutokset Alla joitakin esimerkkejä peruutus- ja palautusprosesseista. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 21 / 129 22 / 129 Maksuturvan maksupalvelun integrointiohjeet Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 2.3 Vastaussanomien käsittely 23 / 129 Verkkokaupan 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. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 24 / 129 Maksuturvan maksupalvelun integrointiohjeet 3. Rajapintakuvaukset Kaikki Maksuturvan tuotantoympäristön palveluiden kutsut suoritetaan salattua HTTPStiedonsiirtoprotokollaa käyttäen, esimerkiksi https://www.maksuturva.fi/NewPaymentExtended.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 HTTPtiedonsiirtoprotokollaa , esimerkiksi: http://test1.maksuturva.fi/NewPaymentExtended.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. Parametrin 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. Verkkokaupan tunnus ei ole salainen tieto, vaan sitä käytetään julkisena parametrina esimerkiksi verkkokauppojen sertifikaattisivuilla: https://www.maksuturva.fi/Certificate.pmt? seller_id={VERKKOKAUPAN_TUNNUS]&request_locale=fi. Viestien 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. Verkkokaupan 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. Parametri kertoo, monesko verkkokaupalle kytketty salainen avain on käytössä. Palvelun käytön alussa versionumero on 001. Rajapintakohtaiset kutsuviestien ja vastaussanomien parametrit eritellään tarkemmin kussakin rajapintakuvauksessa. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 25 / 129 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ä POST-metodilla osoitteesta https://www.maksuturva.fi/ GetPaymentMethods.pmt (tai http://test1.maksuturva.fi/GetPaymentMethods.pmt testiympäristössä). Vastauksessa (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. Verkkokaupan tekninen tunnus sellerid 2. Kieli, jolla maksutapojen nimet halutaan request_locale fi, sv, en Muoto Minimipituus P/V AN50 4 P A2 2 V AN17 4 V oletus: fi 3. Tilauksen loppusumma, jota tullaan totalamount esim. 47,50 maksamaan, sisältäen kaikki kulut. Vastaussanomat tiedot Vastaussanoma (XML-dokumentti) palautetaan vastauksena HTTP GET/POST-pyyntöön. XML-sisältö selviää parhaiten alla olevasta esimerkistä. Esimerkki pyynnöstä (GET): https://www.maksuturva.fi/GetPaymentMethods.pmt? sellerid=SELLERID&request_locale=fi&totalamount=47,50 Esimerkki vastauksesta: Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 26 / 129 Maksuturvan maksupalvelun integrointiohjeet <?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 Verkkomaksu</displayname> </paymentmethod> </paymentmethods> Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 3.2 Dynaamisen kuva-aineiston hakeminen 27 Dynaamisten kuva-aineistojen hakemisen rajapintakuvaus, versio 1.0 Tämä rajapinta mahdollistaa verkkokaupan Maksuturvan palveluihin kytkettyjen dynaamisten kuvaaineistojen hakemisen käyttämällä verkkokaupan teknistä tunnusta. Vastauksena tulevan PNG-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) Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] / 129 28 / 129 Maksuturvan maksupalvelun integrointiohjeet bannertype=payment_methods_vertical&rowcolumns=4&request_locale=fi (kun käytössä Posti Maksuturva-palvelu) bannertype=payment_methods_horizontal&rowscolumns=2&request_locale=en (kun käytössä Maksuturva-palvelu) Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 3.2.1 Muutokset Ajankohta Dokumentin Muutos versio Elokuu 2014 1.0 Dynaamisen kuva-aineiston rajapintakuvaus omana rajapintakuvauksenaan. Uusina ominaisuuksina maksutapabannerin koon valinta ja käytössä olevan maksunvälityspalvelun logon noutaminen. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 29 / 129 30 / 129 Maksuturvan maksupalvelun integrointiohjeet 3.2.2 Kuvien hakeminen Verkkokauppakohtainen käytetyn maksupalvelun logo sekä maksutapabannerit ovat haettavissa PNGkuvana 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. Pyyntö Kentän Kenttä numero 1. Verkkokaupan Tiedon nimi Arvo input name= value= sellerid Muoto Minimipituus P/V AN50 4 P tekninen tunnus 2. Bannerin tyyppi bannertype logo A50 V payment_methods_vertical payment_methods_horizontal 3. Kielikoodi request_locale fi, en, sv. Oletus: fi A2 2 V 4. Bannerin koko rowscolumns horizontal: 2 – 6, N2 1 V riveinä tai vertical: 2 – 20 palstoina Oletus: 3 Vastaus on redirect (HTTP 302) PNG-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" /> Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 31 3.2.3 Maksutapabannerin linkittäminen palvelun sertifikaattisivuun Maksuturva- ja Posti 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. Verkkokaupan tekninen Tiedon nimi Arvo input name= value= sellerid request_locale fi, en, sv. Oletus: fi Muoto Minimipituus P/V AN50 4 P A2 2 V 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> Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] / 129 32 / 129 Maksuturvan maksupalvelun integrointiohjeet 3.3 Maksaminen Maksuturvan Maksurajapinnan kuvaus, versio 4.1.11 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. Paluuosoitteet 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. Verkkokaupan tulee tällöin hakea valittavissa olevat maksutavat tilauskohtaisesti käyttämällä Maksutapojen hakeminen -rajapintaa. Verkkokauppa 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ä. Tilauksen vastaanottajan osoite 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. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 3.3.1 Muutokset Ajankohta Dokumentin Muutos versio Marraskuu 2.5 Paluusanoman kuvaukseen lisätty pmt_paymentmethod -kentän kuvaus. 4.0 Uusi rajapintaversio: 0004 2010 Helmikuu 2011 MAKSUN VÄLITYKSEN TIEDOT (IN): Valinnaiset 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_PAYMENT_EXTENDED) • sisään tulevan datan ja verkkokaupan enkoodaus (pmt_charsethttp) Tuki maksutavan esivalinnalle verkkokaupassa: Verkkokaupassa 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ö (ALV mukana) (pmt_row_price_grossN) • Tilausrivin tuotteen nettohinta per yksikkö (ilman ALV:a) (pmt_row_price_netN) • Tilausrivin tuotteeseen sovellettu ALV-prosentti (pmt_row_vatN) • Tilausrivin tyyppi (pmt_row_typeN) Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 33 / 129 34 / 129 Maksuturvan maksupalvelun integrointiohjeet Pakollinen 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 VASTAUSSANOMAN TIEDOT (OUT) Valittu maksutapa (pmt_paymentmethod) uudet koodit ja selitteet: • FI70 - Maksuturva-Lasku (luotto- ja rahoituspalvelu) • FI71 - Maksuturva-Osamaksu (luotto- ja rahoituspalvelu) • FI80 - Maksuturva-Paypal Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet • FI90 - Maksuturva-KV-tilisiirto Tulevien ominaisuuksien tueksi: (pmt_escrow) Uusi kenttä: • pmt_action (NEW_PAYMENT_EXTENDED) Uusia kenttiä tarkisteessa: • pmt_action (NEW_PAYMENT_EXTENDED) • pmt_version Toukokuu 4.1 2011 MAKSUN VÄ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 Pidennetty 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 POP Pankin maksutavat. 4.1.11 Lisätty vastaussanoman kuvaukseen, että pmt_sellercosts -muuttujan arvo nousee vastaussanomassa, 2014 Elokuu 2014 Syyskuu 2014 Lokakuu 2014 jos valitussa maksutavassa on käytössä laskutuslisä Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 35 / 129 36 / 129 Maksuturvan maksupalvelun integrointiohjeet 3.3.2. Maksuviestin tiedot Verkkokauppa välittää maksun tiedot POST-metodia käyttäen <form>-tietoryhmässä piilomuuttujina (<input type=hidden>) . Tiedot lähetetään osoitteeseen https://www.maksuturva.fi/NewPaymentExtended.pmt (tai http://test1.maksuturva.fi/NewPaymentExtended.pmt testiympäristössä) Kentän Kenttä numero 1. Toiminnon Tiedon nimi Arvo input name= value= Muoto Minimipituus P/V pmt_action NEW_PAYMENT_EXTENDED AN50 4 P 4 P tunniste 2. Sanoman versio pmt_version 0004 AN4 3. Verkkokaupan pmt_sellerid AN15 pmt_selleriban AN30 AN20 N20 4 P kuluva päivä muodossa AN10 10 P P tunnus 4. Verkkokaupan 18 V tilinumero 5. Maksun tunnus pmt_id 6. Tilausnumero pmt_orderid 7. Maksun viite pmt_reference 8. Maksun eräpäivä pmt_duedate AN50 P P dd.mm.yyyy 9. Ostajan locale pmt_userlocale fi_FI, sv_FI, en_FI AN5 5 V 10. Maksun pmt_amount AN17 4 P AN3 3 P rahamäärä 11. Maksun valuutta pmt_currency EUR 12. Ok -paluuosoite pmt_okreturn AN200 13. Virhe - pmt_errorreturn pmt_cancelreturn P AN200 AN200 P AN200 P P paluuosoite 14. Peruutus paluuosoite 15. Viivästetty maksu pmt_delayedpayreturn -paluuosoite 16. Escrow käytössä pmt_escrow Tyytyväisyystakuu- A1 1 P palvelu=Y Suoramaksupalvelu=N 17. Escrow pmt_escrowchangeallowed N A1 1 P pmt_invoicefromseller Y/N A1 1 V pmt_paymentmethod FINN (esim. FI01) AN4 4 V pmt_buyeridentificationcode AN11 9 V AN100 valittavissa 18. Lähettääkö verkkokauppa laskun 19. Verkkokaupassa esivalittu maksutapa 20. Ostajan hetu tai y-tunnus 21. Ostajan nimi pmt_buyername 22. Ostajan osoite pmt_buyeraddress AN100 Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] P P Maksuturvan maksupalvelun integrointiohjeet 23. Ostajan 37 N20 P AN100 A2 P pmt_buyercountry pmt_buyerphone AN40 V pmt_buyeremail AN100 V pmt_deliveryname AN100 P pmt_deliveryaddress AN100 P pmt_deliverypostalcode N20 P pmt_deliverycity AN100 P pmt_deliverycountry A2 P pmt_sellercosts n,nn pmt_rows pmt_buyerpostalcode postinumero 24. Ostajan kaupunki pmt_buyercity 25. Ostajan P maakoodi (FI, SE, EN…) 26. Ostajan puhelinumero 27. Ostajan sähköposti 28. Vastaanottajan nimi 29. Vastaanottajan osoite 30. Vastaanottajan postinumero 31. Vastaanottajan kaupunki 32. Vastaanottajan maakoodi (FI, SE, EN…) 33. Myyjän / AN17 4 P N4 1 P pmt_row_nameN AN40 1 P pmt_row_descN AN1000 1 P pmt_row_quantityN N8 1 P pmt_row_articlenrN AN10 0 V pmt_row_unitN esim. kg, kpl AN3 0 V pmt_row_deliverydateN dd.mm.yyyy AN10 10 P pmt_row_price_grossN n,nn AN17 4 P/V toimittajan käsittelykulut 34. Tilausrivien lukumäärä 35. Tilausrivin tuotteen nimi 36. Tilausrivin tuotteen kuvaus 37. Tilausrivin tuotteen määrä 38. Tilausrivin tuotteen tuotenumero kaupassa 39. Tilausrivin määrän yksikkö 40. Tilausrivin toimituksen tai palvelun suorituksen ajankohta 41. Tilausrivin tuotteen bruttohinta per yksikkö (ALV mukana) Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] / 129 38 / 129 42. Maksuturvan maksupalvelun integrointiohjeet Tilausrivin pmt_row_price_netN n,nn AN17 4 P/V pmt_row_vatN n,nn AN5 4 P AN5 4 P N5 1 P tuotteen nettohinta per yksikkö (ilman ALV:a) 43. Tilausrivin tuotteeseen esim. 24,00 sovellettu ALVprosentti 44. 45. Tilausrivin pmt_row_discountpercentageN n,nn alennus-prosentti esim. 10,00 Tilausrivin tyyppi pmt_row_typeN 1 = tuote 2 = postikulu 3 = käsittelykulu 4 = räätälöity tuote (ei palautusoikeutta) 5 = palvelu 6 = alennus (rahamäärä) 46. Tarkisteen pmt_charset laskentamerkistö 47. Sisään tulevan ISO-8859-1, ISO-8859-15 tai AN15 P AN15 P P UTF-8 pmt_charsethttp datan enkoodaus ISO-8859-1, ISO-8859-15 tai UTF-8 (ja verkkokaupan enkoodaus selaimen suuntaan) 48. Tarkistetiedon pmt_hashversion AN10 AN128 versio 49. Tarkiste pmt_hash 50. Avaimen pmt_keygeneration N3 32 P P sukupolvi Merkintä ANxx tarkoittaa, että kenttä sisältää enintään xx aakkosnumeerista merkkiä. P tarkoittaa pakollista tietoa ja V valinnaista. P/V tarkoittaa ehdollisesti pakollista tietoa (esim. kaksi toisillensa vaihtoehtoista tietoa, kuten pmt_row_price_grossN ja pmt_row_price_netN). Minimipituus valinnaisten kenttien kohdalla ei tarkoita, että kyseisessä kentässä pitää aina olla sen mittainen merkkijono. Valinnainen kenttä voi uupua kokonaan pyynnöstä tai sen arvo voi olla tyhjä. Toki mikäli valinnainen tieto ei ole tyhjä, on se oltava vähintään minimipituuden mittainen. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 3.3.2.1 Kenttien selitteet - Maksun välityksen tiedot Kentän Kenttä Selite numero 1. Toiminnon tunniste NEW_PAYMENT_EXTENDED 2. Sanoman versio Maksusanoman sisällön määrittelyversio. 3. Verkkokaupan tunnus Suomen Maksuturva Oy:n Kauppiaalle tunnistamista varten antama tunnus. 4. Verkkokaupan Ei käytössä toistaiseksi. Hyvityksen kohdetilinumero (IBAN-muodossa), jos hyvitys halutaan eri tilinumero tilille kuin mikä sopimukselta löytyy. Toistaiseksi hyväksytään vain suomalaisia tilinumeroita IBAN -muodossa. 5. Maksun tunnus Verkkokaupan maksulle antama yksilöivä tunnus. 6. Tilausnumero Tilausnumero, jolla tilaus löytyy verkkokaupan järjestelmästä ja joka on ostajalla tiedossa. 7. Maksun viite Viitenumero, jota Suomen Maksuturva Oy käyttää hyvittäessään rahat toimituksen jälkeen kauppiaalle. Viitenumeron tulee täyttää Finanssialan keskusliiton (FK, http://www.fkl.fi) säännöt viitenumeron muodolle. Viitenumeron minimipituus on 4, joista viimeinen on tarkiste. 8. Maksun eräpäivä Nykyisin: Kuluva päivä. PP.KK.VVVV 9. Ostajan locale Tieto, joka kertoo ostajan kielen ja maan esim. fi_FI, sv_FI tai en_FI kun toimitaan Suomessa. Jos ei annettu, palvelu käyttää sisäisesti arvoa fi_FI Kieli: ISO 639-1 Maa: ISO 3166-1 alpha-2 10. Maksun rahamäärä Loppusumma, sisältäen tilausrivit tyyppejä 1,4,5,6. Jos myyjän kuluja ei ole, tämä on sama kuin koko tilauksen loppusumma. Summa tulee esittää aina kahden desimaalin tarkkuudella. Desimaalierottimena käytetään pilkkua esim. 94,80 11. Maksun valuutta Maksussa käytettävä valuutta. Aina EUR. 12. Ok -paluuosoite Osoite, mihin käyttäjän selain ohjataan onnistuneen maksun jälkeen. 13. Virhe -paluuosoite Osoite, mihin käyttäjän selain ohjataan, jos maksamisessa tapahtuu virhe. Osoitteen perään lisätään ns. querystring -parametrina sisään tullut maksun tunnus pmt_id nimellä. 14. Peruutus - Osoite, mihin käyttäjän selain ohjataan hänen valitessaan maksun peruutuksen. Jos Virhe- paluuosoite paluuosoitetta ei ole annettu, ohjataan käyttäjän selain myös virhetilanteissa Peruutuspaluuosoitteeseen. Osoitteen perään lisätään ns. querystring -parametrina sisään tullut maksun tunnus pmt_id nimellä. 15. Viivästetty maksu - Osoite, mihin käyttäjän selain ohjataan hänen valitessaan maksutavakseen esim. tilisiirron. paluuosoite Osoitteen perään lisätään ns. querystring -parametrina sisään tullut maksun tunnus pmt_id nimellä. Tilisiirtoa ei tueta enää nykyisissä valmispaketeissa. Siksi usein ehdotammekin käytettävän viivästetty maksu-paluuosoitteeseena samaa osoitetta kuin peruutusten tapauksessa (pmt_delayedpayreturn ~= pmt_cancelreturn). 16. Escrow käytössä Kertoo onko kyseessä Escrow-maksu. Arvot: Y/N Tyytyväisyystakuun sisältävissä Maksuturva-palveluissa (esim. Maksuturva Basic tai Gold) arvo on aina Y. Suoramaksupalveluissa (esim. eMaksut) arvo on aina N. 17. Escrow valittavissa Toistaiseksi aina N. 18. Lähettääkö Parametria voidaan käyttää, mikäli maksutapa on lasku tai osamaksu: verkkokauppa laskun Y = verkkokauppa lähettää laskun N (OLETUS) = Maksuturva tai rahoituspalvelun tarjoaja lähettää laskun ostajalle Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 39 / 129 40 / 129 19. Maksuturvan maksupalvelun integrointiohjeet Esivalittu maksutapa VALINNAINEN. Maksutavan koodi FInn. Kts. maksutavat vastauksen tiedoista kappaleesta Kenttien selitteet - Maksun vastaussanoman tiedot. 20. Ostajan hetu tai y- Ostajan henkilö- tai y-tunnus. tunnus 21. Ostajan nimi Laskutusosoitteen (ostajan) nimi. 22. Ostajan osoite Laskutusosoitteen (ostajan) postiosoite (katuosoite tai postilokero). 23. Ostajan postinumero Laskutusosoitteen (ostajan) postinumero. 24. Ostajan kaupunki Laskutusosoitteen (ostajan) kaupunki tai muu paikkakunta. 25. Ostajan maa Laskutusosoitteen (ostajan) maan maakoodi. (ISO 3166-1 alpha-2 standardin mukainen 2-merkkinen maakoodi http://fi.wikipedia.org/wiki/ ISO_3166) 26. Ostajan Laskutusosoitteen (ostajan) puhelinnumero. puhelinnumero 27. Ostajan sähköposti Laskutusosoitteen (ostajan) sähköpostiosoite. 28. Vastaanottajan nimi Toimitusosoitteen (vastaanottajan) nimi. 29. Vastaanottajan osoite Toimitusosoitteen (vastaanottajan) osoite. (* 30. Vastaanottajan Toimitusosoitteen (vastaanottajan) postinumero. (* postinumero 31. Vastaanottajan Toimitusosoitteen (vastaanottajan) kaupunki tai paikkakunta. (* kaupunki 32. Vastaanottajan maa Toimitusosoitteen (vastaanottajan) maan maakoodi. (* 2 merkkiä; ISO 3166-1 alpha-2 33. Myyjän / toimittajan Summa tulee esittää aina kahden desimaalin tarkkuudella. Desimaalierottimena käytetään käsittelykulut pilkkua esim. 21,00 pmt_sellercosts kentän arvon on oltava tilausriveillä esiintyvien posti- ja käsittelykulujen yhteenlaskettu summa (rivityypit 2 ja 3). 34. 35. 36. Tilausrivien Tilauksessa on eriteltävä tilatut tuotteet (versiosta 0004 alkaen). lukumäärä Tässä kerrotaan tilausrivien lukumäärä kokonaislukuna. Tilausrivin tuotteen Tilausrivin tuotteen nimi. Voi olla myös muuta kuin fyysinen tuote. Tällöin kentässä ”Tilausrivin nimi tyyppi” voi olla muu tyyppi kuin 1. Max 40 merkkiä. Tilausrivin tuotteen Tilausrivin tuotteen tarkempi kuvaus. kuvaus 37. 38. Tilausrivin tuotteen Kokonaisluku. Kuinka monta ko. tilausrivillä olevaa tuotetta tilaus sisältää. määrä Ks. kohta “Tilauserittelyn laskentasäännöt”. Tilausrivin tuotteen Tuotteen numero tai koodi verkkokaupassa. Valinnainen tieto. tuotenumero verkkokaupassa 39. Tilausrivin tuotteen Yksikkö määrälle, esim. kg, l, m, kpl määrän yksikkö 40. Tilausrivin Päivämäärä muodossa dd.mm.yyyy - annetaan kuluva päivä, mikäli tilausrivi ei toimituksen tai sisällä arvoa palvelun suorituksen ajankohta 41. Tilausrivin tuotteen Tilausrivin yksittäisen tuotteen bruttohinta, eli hinta joka sisältää ALV:n, mutta ei ole alennettu. bruttohinta per Netto- tai bruttohinta on välitettävä, mutta ei molempia! yksikkö (ALV mukana) Ks. kohta “Tilauserittelyn laskentasäännöt”. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 42. 43. Tilausrivin tuotteen Tilausrivin yksittäisen tuotteen nettohinta, eli hinta ilman ALV:a, ei ole alennettu. Netto- tai nettohinta per bruttohinta on välitettävä, mutta ei molempia! yksikkö (ilman ALV:a) Ks. kohta “Tilauserittelyn laskentasäännöt”. Tilausrivin Tilausrivin tuotteeseen sovellettu ALV-prosentti. Desimaaliluku kahdella desimaalilla. Esim. tuotteeseen 23,00. sovellettu ALV- Ks. kohta “Tilauserittelyn laskentasäännöt”. prosentti 44. Tilausrivin alennus- Tilausriviin sovellettava alennusprosentti. Ks. kohta “Tilauserittelyn laskentasäännöt”. prosentti 45. Tilausrivin tyyppi 1 = tuote 2 = postikulu 3 = käsittelykulu 4 = räätälöity tuote (ei palautusoikeutta) 5 = palvelu 6 = alennus (aina negatiivinen) 46. Tarkisteen Tämä kertoo missä merkistössä tarkisteen laskentaan käytetty merkkijono oli tarkistetta laskentamerkistö laskettaessa. Sallitut arvot toistaiseksi ovat ISO-8859-1, ISO-8859-15 ja UTF-8. Tarkiste lasketaan binäärisestä muodosta, eikä merkkijonosta, kuten hash-algoritmien toteuttavien funktioiden rajapinnoista voisi päätellä. Muunnos merkkijonomuotoisesta binääriseksi on osattava tehdä oikeassa merkistössä. Mikäli merkistö ei ole määriteltävissä käytettävälle hash-toteutukselle, on selvitettävä mitä merkistöä se sisäisesti käyttää. 47. Sisään tulevan Tämä kertoo sisään tulevan datan enkoodauksen. datan enkoodaus Maksurajapinta käsittelee http request parametrit tämän merkistön mukaisesti. Käytännössä se (ja verkkokaupan on siis se merkistö, minkä selain kertoo olevan käytössä kun verkkokaupassa asioidaan. enkoodaus selaimen suuntaan) 48. Tarkistetiedon versio Tarkisteen laskennassa käytetty laskentaversio (algoritmin nimi, katso tarkempi kuvaus Rajapintojen Integrointiohjeesta) 49. Tarkiste Sanoman kentistä ja verkkokaupan salaisesta avaimesta laskettu tarkiste. Tarkiste lasketaan seuraavista kentistä: • 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 Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 41 / 129 42 / 129 Maksuturvan maksupalvelun integrointiohjeet • pmt_buyerpostalcode • pmt_buyercity • pmt_buyercountry • pmt_deliveryname • pmt_deliveryaddress • pmt_deliverypostalcode • pmt_deliverycity • pmt_deliverycountry • pmt_sellercosts • 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> Tarkemmat ohjeet tarkisteen laskentaan. 50. Avaimen sukupolvi Verkkokaupan salaisen avaimen sukupolvinumero. *) 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. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 43 / 129 3.3.2.2 Tilauserittely Tilauserittely eli pmt_row -alkuiset tiedot on rajapinnassa 0004 pakollinen, ja sisältää kattavat tiedot tilauksesta. Tilauserittelyn loppusumman on täsmättävä tilauksen kokonaissumman kanssa (pmt_amount + pmt_sellercosts). Tilauserittelyssä voidaan välittää joko tuotekohtainen netto- tai bruttohinta. Molempia ei saa välittää. Hintojen välittäminen nettona Mikäli verkkokaupassa lähtötietona on nettohinta, josta verkkokauppa laskee bruttohinnan, on suositeltavaa välittää nettohinta (pmt_row_price_net) ja ALV-prosentti. Tällöin myös Maksuturvan järjestelmä laskee summia tarkistaessaan bruttohinnan lähtien nettohinnasta ja ALV-prosentista. Välitettävä hinta: pmt_row_price_net = tuotteen yksikköhinta, ilman ALVia, ilman alennuksen huomiointia Hintojen välittäminen bruttona Mikäli verkkokaupassa lähtötietona on bruttohinta (ALVillinen hinta), josta verkkokauppa laskee tilauserittelyä varten nettohinnan, on suositeltavaa välittää bruttohinta ja ALV-prosentti. Tällöin Maksuturvan järjestelmä laskee tarvittaessa nettohinnan tilauserittelyyn välittäessään tiedot eteenpäin sellaisille maksu- tai luottopalveluille, jotka tietoja vaativat. Mikäli Maksuturvan laskemista nettohinnoista saatu tilauserittelyn kokonaishinta ei täsmää alkuperäiseen verkkokaupan pyytämään kokonaishintaan, Maksuturva lisää tilauserittelyyn pyöristyksen korjausrivin. Välitettävä hinta: pmt_row_price_gross = tuotteen yksikköbruttohinta, sisältäen ALV:n, mutta ilman alennuksen huomiointia Alennusten käsittely Alennus voidaan välittää joko rivikohtaisena alennusprosenttina tai vaihtoehtoisesti voidaan välittää erillisiä negatiivisia alennusrivejä. Suositeltavaa on välittää alennukset prosentteina kunkin tuoterivin yhteydessä. Tällöin niitä on helpompi käsitellä esim. peruutustilanteissa, kun alennus ei näy erillisenä rivinä ja alennusta ei siten tarvitse erikseen peruuttaa. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 44 / 129 Maksuturvan maksupalvelun integrointiohjeet 3.3.2.3 Tilauserittelyn laskentasäännöt Alla olevassa kuvauksessa pmt -alkuiset tiedot ovat rajapinnassa välitettyjä tietoja. Calc -alkuiset tiedot ovat laskettuja ja niitä käytetään tilauserittelyn summien tarkistamisessa. Rivin tuotteen yksikköbruttohinnalla ja yksikkönettohinnalla on seuraava suhde: pmt_row_price_gross = round ( pmt_row_price_net * ( 1 + 0.01 * pmt_row_vat ) ) JOS on välitetty nettohinta (ALViton hinta), eli pmt_row_price_net: Rivin summa alennus huomioiden, ilman ALVia: CalcRowAmountExVAT = round ( round ( pmt_row_quantity * pmt_row_price_net ) * ( 1 - 0.01 * pmt_row_discountpercentage ) ) JOS on välitetty bruttohinta (ALVillinen hinta), eli pmt_row_price_gross: Rivin summa alennus huomioiden, ilman ALVia: CalcRowUnitNetPrice = round ( pmt_row_price_gross / ( 1 + 0.01 * pmt_row_vat ) ) CalcRowAmountExVAT = round ( round ( pmt_row_quantity * CalcRowUnitNetPrice ) * ( 1 - 0.01 * pmt_row_discountpercentage ) ) Rivin ALV-rahasumma (ALV lasketaan alennetun nettohinnan päälle, alennus huomioidaan): CalcRowVAT = round (CalcRowAmountExVAT * ( 0.01 * pmt_row_vat )) Rivin kokonaissumma (vaikutus maksettavaan bruttosummaan): CalcTotalRowAmount = round ( CalcRowAmountExVAT + CalcRowVAT ) Koko tilauksen bruttosumma: == pmt_amount + pmt_sellercosts == summa ( CalcTotalRowAmount ) pmt_amount == CalcTotalRowAmount yhteenlaskettu summa (tilausrivin tyypit 1, 4, 5, 6) pmt_sellercosts == posti- ja käsittelykulurivien yhteenlaskettu summa (tilausrivin tyypit 2, 3) Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 3.3.3 Maksuviestin vastauksen tiedot 45 / 129 Maksun vastaussanoma välitetään ok-paluuosoitteeseen, mikäli asiakas on maksanut maksun. Tällöin toimituksen voi aloittaa. Mikäli asiakas vahvisti käyttävänsä tilisiirtoa, välitetään maksun tunnus viivästetty maksu -paluuosoitteeseen. Mikäli maksaja perui tapahtuman, maksun tunnus välitetään peruutus-paluuosoitteeseen. Virhetapauksissa maksun tunnus välitetään virhe-paluuosoitteeseen tai sen puuttuessa peruutus-paluuosoitteeseen. HUOM! Maksajan peruuttamasta tapahtumasta, virheestä ja viivästetystä maksusta välitetään paluuosoitteeseen ainoastaan tieto pmt_id. Lähtökohtaisesti myyjän kulut (pmt_sellercosts) vastaussanomassa ovat samat kuin verkkokaupan maksuviestissä ilmoitetut myyjän kulut. Osalle Maksuturvan maksutavoista on kuitenkin mahdollista lisätä tilauksen maksajan maksettavaksi kiinteä euromääräinen laskutuslisä. Kun ostaja valitsee tällaisen maksutavan, laskutuslisä lisätään tilauksen tietoihin uutena erittelyrivinä, jonka summa kasvattaa myyjän kulujen (pmt_sellercosts) arvoa. Tällaisten maksutapojen osalta Verkkokaupan tulee maksuviestin vastaussanoman kohdalla varautua pmt_sellercosts -muuttujan arvon nousuun laskutuslisän verran. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 46 / 129 Maksuturvan maksupalvelun integrointiohjeet 3.3.3.1 Vastauksen tietojen tarkistaminen Verkkokaupasta Maksuturvalle ja takaisin välitettävien tietojen osalta on ehdottomasti tarkistettava tietojen muuttumattomuus. Maksuturvan välittämät erilliset vastaustiedot on lisäksi tarkistettava muodollisesti, rajapintakuvauksen mukaan. Vastauksen tiedoista on laskettava tarkiste ja verrattava sitä vastauksessa olevaan tarkisteeseen. Jos kaikki yllä olevat vaiheet menevät onnistuneesti läpi, voidaan melko suurella varmuudella katsoa vastaussanoman olevan validi ja käsitellä se asianmukaisesti. Kentän Kenttä numero Tiedon nimi Arvo input name= value= Muoto P/V 1. Toiminnon tunniste pmt_action NEW_PAYMENT_EXTENDED AN50 P 2. Sanoman versio pmt_version AN4 P 3. Maksun tunnus pmt_id AN20 P 4. Maksun viite pmt_reference N20 P 5. Maksun rahamäärä pmt_amount N17 P 6. Maksun valuutta pmt_currency AN3 P 7. Myyjän kulut pmt_sellercosts N17 P 8. Maksutapa pmt_paymentmethod AN4 P 9. Escrow käytössä pmt_escrow AN1 P 10. Tarkiste pmt_hash Y/N Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] AN128 P Maksuturvan maksupalvelun integrointiohjeet 3.3.3.2 Kenttien selitteet - Maksun vastaussanoman tiedot Kentän Kenttä Selite numero 1. Toiminnon NEW_PAYMENT_EXTENDED tunniste 2. Sanoman Maksusanoman sisällön määrittelyversio. Sama kuin vastaanotetussa sanomassa. versio 3. Maksun Verkkokaupan maksulle antama yksilöivä tunnus. tunnus 4. Maksun viite Viite, jota Suomen Maksuturva Oy käyttää hyvittäessään rahat toimituksen jälkeen kauppiaalle. Tämä on aina ns. teknisessä muodossa, eli etunollilla ilman välilyöntejä. Myös vastauksen tarkiste on laskettu käyttäen teknistä muotoa. 5. 6. Maksun Tilauksen tuotteiden ja palveluiden loppusumma. Summa esitetään aina kahden desimaalin tarkkuudella. rahamäärä Desimaalierottimena käytetään pilkkua esim. 94,80 Maksun Maksussa käytetty valuutta. valuutta 7. Myyjän kulut Tilauksen toimitus- ja käsittelykulujen loppusumma. Summa esitetään aina kahden desimaalin tarkkuudella. Desimaalierottimena käytetään pilkkua esim. 7,40 8. Maksutapa Kertoo, millä maksutavalla maksu on suoritettu. Koodi Selite (tulee näkyä verkkokauppapaikan hallintapaneelissa) FI01 Nordea E-maksu FI02 Danske Bank Verkkomaksu FI03 Aktia verkkomaksu FI04 POP Pankin verkkomaksu FI05 Tapiola Pankki Verkkomaksu FI06 Osuuspankki Verkkomaksu FI07 Ålandsbanken E-maksu FI08 Säästöpankin verkkomaksu FI09 Handelsbanken Verkkomaksu FI10 S-pankki Verkkomaksu FI50 Korttimaksu (Visa, Visa Electron, MasterCard) FI60 Maksuturva Lasku FI61 Maksuturva Erämaksu FI70 SveaWebPay Lasku FI71 SveaWebPay Osamaksu FI72 Yrityslasku USPP PayPal RBIN Resurs Bank Lasku RBPP Resurs Bank Osamaksu HUOM! Älä käytä yllä olevan taulukon arvoja tuotannossa. Nouda sen sijaan viralliset koodit ja selitteet GetPaymentMethods.pmt-rajapinnan (ks. kappale 6) kautta käyttäen omaa verkkokauppatunnustasi (sellerid). Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 47 / 129 48 / 129 9. Maksuturvan maksupalvelun integrointiohjeet Escrow Kertoo onko kyseessä Escrow-maksu. Arvot: Y/N käytössä Tyytyväisyystakuun sisältävissä Maksuturva-palveluissa (esim. Maksuturva Basic tai Gold) arvo on aina Y. Suoramaksupalveluissa (esim. eMaksut) arvo on aina N. 10. Tarkiste Sanoman kentistä ja verkkokaupan salaisesta avaimesta laskettu tarkiste. Tarkisteen laskennassa käytetään samoja versio-, avain- ym. tietoja kuin sisään tulevalla sanomalla. Tarkiste lasketaan näistä kentistä: • pmt_action • pmt_version • pmt_id • pmt_reference • pmt_amount • pmt_currency • pmt_sellercosts • pmt_paymentmethod • pmt_escrow Tarkemmat ohjeet tarkisteen laskentaan. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 49 / 129 3.4 Maksutapahtuman tilan kysely Maksutapahtuman tilan kyselyn rajapintakuvaus, versio 5.0.5 Palvelusta voi tarkistaa (Tyytyväisyystakuun tai suoramaksun) toimeksiannon tilan. Vastaussanomasta käy ilmi toimeksiannon tila, joista toimenpiteitä voivat vaatia: • asiakas on maksanut maksun, jolloin toimitustiedot pitäisi syöttää (vastauskoodi 20) • asiakas on peruuttanut toimeksiannon, jolloin mahdollisen palautuksen jälkeen myös verkkokaupan tulee peruuttaa toimeksianto (vastauskoodi 91) Huomioithan, että Tyytyväisyystakuu-palveluiden tapauksessa vastauskoodien määrä on laajempi kuin suoramaksupalveluiden tapauksessa. Ainoastaan Tyytyväisyystakuu-palvelua koskevat vastauskoodit on merkitty dokumenttiin tekstillä ”(Tyytyväisyystakuu)”. Miten ja milloin tulisi käyttää Tapahtuman tilan kyselyä suositellaan käytettävän myös niiden tilausten tapauksessa, jotka on peruutettu ennen maksamista tai vaikuttavat siltä. Eli myös niiden tapahtumien tilaa tulisi kysellä, joiden tapauksessa ostaja on palannut verkkokauppaan peruutus- tai virhepaluuosoitteella. Sopiva ajankohta ensimmäiselle tilan kyselylle on yksi (1) tai kaksi (2) tuntia tilauksen maksamisen aloittamisen jälkeen. Tällä tavoin tulee hoidettua suurin osa tilanteista. Mikäli Maksuturva ei tiedä maksun tilaa tuona ajanhetkenä, kysellään maksun tilaa pankista. Joissakin harvinaisissa, mutta ajoittain ilmenevissä, tapauksissa maksun tilan kysely pankista ei koskaan onnistukaan, mutta sitten myöhemmin yhden tai kahden pankkipäivän kuluttua ostajan rahat löydetäänkin Maksuturvan asiakasvarat-pankkitililtä. Kun näin tapahtuu, Maksuturva merkitsee maksun maksetuksi, mistä eteenpäin Tapahtuman tilan kysely -rajapinta vastaa verkkokaupalle maksun olevan maksettu. Tästä johtuen tilauksille, joiden maksun tila on epäselvä, olisi suotavaa kysellä tilaa Tapahtuman tilan kysely -rajapinnan kautta esim. kerran päivässä joidenkin pankkipäivien ajan tilauksen luomisesta alkaen. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 50 / 129 Maksuturvan maksupalvelun integrointiohjeet 3.4.1 Muutokset Muutospäivä Dokumentin Muutos versio Marraskuu 2010 2.5 Paluusanoman kuvaukseen lisätty pmt_paymentmethod -kentän kuvaus. Tammikuu 2011 4.0 Uusi rajapintaversio: 0004 KYSELYN PYYNNÖN TIEDOT (IN) Uusia tietoja: - pmtq_action (PAYMENT_STATUS_QUERY) Uusia tietoja pyynnön tarkisteessa: - pmtq_action (PAYMENT_STATUS_QUERY) - pmtq_version KYSELYN VASTAUSSANOMAN TIEDOT (OUT) Versiosta 0004 alkaen vastaussanoman enkoodaus on UTF-8. Lisäksi ainoa tuettu vastauksen muoto on XML, eli HTML ei ole enää tuettuna. Nämä muutokset johtuvat siitä, että osamaksulle ja laskulle palautettavat luottotietohausta saadut ostajan osoitetiedot voivat sisältää muitakin kuin ISO-8859-1 merkistön merkkejä. Uusia tietoja: - pmtq_action (PAYMENT_STATUS_QUERY) - Tulevien ominaisuuksien tueksi (valinnainen): (pmtq_escrow) - Valittu maksutapa (valinnainen): (pmtq_paymentmethod) Uusia tietoja pyynnön tarkisteessa: - pmtq_action (PAYMENT_STATUS_QUERY) - pmtq_version - pmtq_paymentmethod - pmtq_escrow Syyskuu 2011 4.0.1 Lisätiedot eMaksujen integrointiin. Maaliskuu 2012 4.0.2 Tiedon pmtq_amount kuvausta korjattu. Elokuu 2012 4.0.3 Vastauksen tyyppinä tuetaan ainoastaan XML-muotoa. Toukokuu 2013 4.0.4 Poistettu ostajan osoitetiedot vastauksesta, sekä niihin liittyvät ohjeistukset. Maaliskuu 2012 5.0 Uusi rajapintaversio: 0005 KYSELYN VASTAUSSANOMAN TIEDOT (OUT) Uusia tietoja: - pmtq_certification - pmtq_externalcode1 - pmtq_externalcode2 - pmtq_externaltext - pmtq_paymentstarttimestamp - pmtq_paymentdate Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet Uusia tietoja vastauksen tarkisteessa: - pmtq_certification (jos saatavilla) - pmtq_paymentdate (jos saatavilla) Lisäksi: Tiedon pmtq_amount kuvausta korjattu. Lokakuu 2013 5.0.1 Lisätty kappale ”Miten ja milloin käytetään”. Tammikuu 2014 5.0.2 Korjattu vastauskoodin 99 kuvaus. Huhtikuu 2014 5.0.3 Lisätty uudet maksutavat: - Maksuturva Lasku - Maksuturva Erämaksu Syyskuu 2014 5.0.4 Nimetty uudelleen Aktian, Säästöpankin ja POP Pankin maksutavat. Lokakuu 2014 5.0.5 Yhdenmukaistettu Maksuturvan palvelutyyppien termistö muun dokumentaation kanssa Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 51 / 129 52 / 129 Maksuturvan maksupalvelun integrointiohjeet 3.4.2 Tapahtuman tilan kyselyn tiedot Tapahtuman tilan kysely on sallittu maksulle heti kun maksun tiedot on vastaanotettu ja tallennettu Suomen Maksuturva Oy:lle. Verkkokauppa välittää tapahtuman kyselyn tiedot POST-metodia käyttäen <form>-tietoryhmässä piilomuuttujina (<input type=hidden>) . Tiedot lähetetään osoitteeseen https://www.maksuturva.fi/PaymentStatusQuery.pmt (tai http://test1.maksuturva.fi/PaymentStatusQuery.pmt testiympäristössä) # Kenttä Tiedon nimi Arvo input name= value= Muoto P/V 1. Toiminnon tunniste pmtq_action PAYMENT_STATUS_QUERY AN50 P 2. Sanoman versio pmtq_version 0005 AN4 P 3. Verkkokaupan tunnus pmtq_sellerid AN15 P 4. Maksun tunnus pmtq_id AN20 P 5. Vastauksen tyyppi pmtq_resptype AN4 P 6. Tarkistetiedon versio pmtq_hashversion AN10 P 7. Tarkiste pmtq_hash AN128 P 8. Avaimen sukupolvi pmtq_keygeneration N3 P XML Merkintä ANxx tarkoittaa, että kenttä sisältää enintään xx aakkosnumeerista merkkiä. P tarkoittaa pakollista tietoa ja V valinnaista. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 3.4.2.1 Kenttien selitteet - Tapahtuman tilan kyselyn tiedot # Kenttä 1. Toiminnon Selite PAYMENT_STATUS_QUERY tunniste 2. Sanoman versio Tapahtuman kyselysanoman sisällön määrittelyversio. 3. Verkkokaupan Suomen Maksuturva Oy:n Kauppiaalle tunnistamista varten antama tunnus. tunnus 4. Maksun tunnus Verkkokaupan maksulle antama yksilöivä tunnus. 5. Vastauksen Määrittää missä muodossa vastaussanoma tehdään. Ainoa tuettu vaihtoehto on XML. tyyppi 6. Tarkistetiedon versio 7. Tarkiste Tarkisteen laskennassa käytetty laskentaversio (algoritmin nimi, katso tarkempi kuvaus Rajapintojen Integrointiohjeesta) Sanoman kentistä ja verkkokaupan salaisesta avaimesta laskettu tarkiste. Tarkiste lasketaan kentistä: · pmtq_action · pmtq_version · pmtq_sellerid · pmtq_id Tarkemmat ohjeet tarkisteen laskentaan. 8. Avaimen Verkkokaupan salaisen avaimen sukupolvinumero. sukupolvi Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 53 / 129 54 / 129 Maksuturvan maksupalvelun integrointiohjeet 3.4.3 Tapahtuman tilan kyselyn vastaussanoman tiedot Versiosta 0004 alkaen vastaussanoman enkoodaus on UTF-8. Lisäksi ainoa tuettu vastauksen muoto on XML, eli HTML ei ole enää tuettuna. Nämä muutokset johtuvat siitä, että osamaksulle ja laskulle palautettavat luottotietohausta saadut ostajan osoitetiedot voivat sisältää muitakin kuin ISO-8859-1 tai 15 merkistön merkkejä. # Kenttä Tiedon nimi Arvo input name= value= Muoto P/V 1. Toiminnon tunniste pmtq_action PAYMENT_STATUS_QUERY AN50 P 2. Sanoman versio pmtq_version 0005 AN4 P 3. Verkkokaupan tunnus pmtq_sellerid AN15 P 4. Maksun tunnus pmtq_id AN20 P 5. Maksun rahamäärä pmtq_amount AN17 P 6. Vastauskoodi pmtq_returncode AN2 P 7. Vastausteksti pmtq_returntext AN100 P 8. Seurantakoodit pmtq_trackingcodes AN400 V 9. Myyjän kulut pmtq_sellercosts AN17 V 10. Maksutapa pmtq_paymentmethod AN4 V 11. Escrow käytössä pmtq_escrow AN1 V A1 V AN50 V AN50 V AN200 V dd.MM.yyyy hh:mm:ss AN19 V dd.MM.yyyy AN10 V AN128 P Tyytyväisyystakuu=Y, suoramaksu=N 12. Todennustieto pmtq_certification 13. Maksupalvelun tarjoajan koodi 1 pmtq_externalcode1 14. Maksupalvelun tarjoajan koodi 2 pmtq_externalcode2 15. Maksupalvelun tarjoajan vastausteksti pmtq_externaltext Y,N 16. Hetki, jolloin maksaja siirtyi maksamaan pmtq_paymentstarttimestamp 17. Maksupäivä pmtq_paymentdate 18. Tarkiste pmtq_hash Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 3.4.3.1 Kenttien selitteet - Tapahtuman tilan kyselyn vastaussanoman tiedot # Kenttä Selite 1. Toiminnon tunniste PAYMENT_STATUS_QUERY 2. Sanoman versio Tapahtuman kyselysanoman sisällön määrittelyversio. 3. Verkkokaupan tunnus Suomen Maksuturva Oy:n Kauppiaalle tunnistamista varten antama tunnus. 4. Maksun tunnus Verkkokaupan maksulle antama yksilöivä tunnus. 5. Maksun rahamäärä Sama kuin alkuperäisen maksutapahtuman pmt_amount tieto. Maksun rahamäärää tulee verrata tilauksen rahamäärään, sen on täsmättävä. Mikäli maksua ei löydy (vastauskoodi on ’00’), tässä kentässä on 0,00. 6. Vastauskoodi Kertoo maksun ja tapahtuman tilan. Katso vastauskoodien arvot ja niiden merkitykset kohdasta Vastauskoodien arvot. 7. Vastausteksti Lyhyt sanallinen kuvaus maksun tilasta. 8. Seurantakoodit Tapahtumaan liittyen Maksuturvalle välitetyt toimitustiedot/seurantakoodit. Muoto [XX| XY|YY] 0-n kpl peräkkäin riippuen montako toimitustietoa/seurantakoodia tapahtumalle on välitetty. XX = Toimitustapakoodi XY = Seurantakoodi tai koodittomissa välitetty teksti YY = Toimituksen tila ks ” Toimituksen tilakoodien arvot” taulukko. 9. Myyjän kulut Jos alkuperäisessä maksussa oli mukana pmt_sellercosts, se tieto palautuu tässä. Mikäli tietoa ei ollut alkuperäisessä maksussa, tässä kentässä voi olla arvo ”0,00” 10. Maksutapa Kertoo, millä maksutavalla maksu on suoritettu. Selitteet voivat muuttua, eikä niihin perustuen saa toteuttaa logiikkaa. Arvot ovat: Koodi Selite (tulee näkyä verkkokauppapaikan hallintapaneelissa) FI01 Nordea E-maksu FI02 Danske Bank Verkkomaksu FI03 Aktia verkkomaksu FI04 POP Pankin verkkomaksu FI05 Tapiola Pankki Verkkomaksu FI06 Osuuspankki Verkkomaksu FI07 Ålandsbanken E-maksu FI08 Säästöpankin verkkomaksu FI09 Handelsbanken Verkkomaksu FI10 S-pankki Verkkomaksu FI50 Korttimaksu (Visa, Visa Electron, MasterCard) FI60 Maksuturva Lasku FI61 Maksuturva Erämaksu FI70 SveaWebPay Lasku FI71 SveaWebPay Osamaksu FI72 Yrityslasku USPP PayPal Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 55 / 129 56 / 129 Maksuturvan maksupalvelun integrointiohjeet RBIN Resurs Bank Lasku RBPP Resurs Bank Osamaksu HUOM! Älä käytä yllä olevan taulukon arvoja tuotannossa. Nouda sen sijaan viralliset koodit ja selitteet maksutapojen hakemisen rajapinnan kautta. 11. Escrow käytössä Kertoo onko kyseessä Escrow-maksu. Arvot: Y/N Tyytyväisyystakuun sisältävien toimeksiantojen maksuissa arvona palautetaan aina Y ja suoramaksupalvelun kautta tehdyissä maksuissa aina N. 12. Todennustieto Y = maksu on todennettu, eli sen maksamisessa on käytetty jotain ostajan tunnistuskeinoa. Svea-maksutapojen yhteydessä Maksuturvalla on lisäksi tieto käyttäjän identiteetistä, muiden maksutapojen kanssa ei. N = maksua ei ole todennettu, tai todennuksesta ei ole tietoa. 13. Maksupalvelun tarjoajan Informatiivinen lisätieto. koodi 1 Käytetään virhetilanteissa välittämään ulkoisen maksupalveluntarjoajan virhekoodi 1. Korttimaksuille Luottokunnan LKPRC -koodi. OK-tapauksessa tässä kentässä voidaan välittää arkistointitunnus informatiivisena tietona. 14. Maksupalvelun tarjoajan Informatiivinen lisätieto. koodi 2 Käytetään virhetilanteissa välittämään ulkoisen maksupalveluntarjoajan virhekoodi 2. Korttimaksuille Luottokunnan LKSRC –koodi. 15. Maksupalvelun tarjoajan Informatiivinen lisätieto. vastausteksti Teksti joko onnistumisesta tai virheestä. Jos ulkoinen maksupalveluntarjoaja ei palauta mitään erityistä tekstiä, tämä kenttä voi olla tyhjä, tai siinä voi olla maksun arkistointitunnus tai muu yksilöivä oleva tieto maksupalveluntarjoajalta. 16. Hetki, jolloin maksaja siirtyi maksamaan dd.MM.yyyy hh:mm:ss Ajanhetki, milloin ostaja siirtyi maksupalvelun tarjoajalle. 17. Maksupäivä dd.MM.yyyy Päivä, jona ostaja maksoin. Tai jos em. tietoa ei ole saatavilla, päivä jona Maksuturva näki rahat tiliotteella. 18. Tarkiste Sanoman kentistä ja verkkokaupan salaisesta avaimesta laskettu tarkiste. Tarkisteen laskennassa käytetään samoja versio-, avain- ym. tietoja kuin sisään tulevalla sanomalla. Tarkiste lasketaan kentistä: • pmtq_action • pmtq_version • pmtq_sellerid • pmtq_id • pmtq_amount • pmtq_returncode • pmtq_returntext • pmtq_sellercosts (jos saatavilla) • pmtq_paymentmethod (jos saatavilla) • pmtq_escrow (jos saatavilla) • pmtq_certification (jos saatavilla) • pmtq_paymentdate (jos saatavilla) Tarkemmat ohjeet tarkisteen laskentaan. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 57 3.4.3.1.1 Vastauskoodien arvot Vastauskoodi 00 00 Lyhyt selite Kuvaus Ei maksettu. Ei maksettu. Jos lisäksi pmtq_amount = 0,00: Jos lisäksi pmtq_amount = 0,00: Tilausta ei ole olemassakaan TAI se on luotu Tilausta ei ole olemassakaan TAI se on luotu muttei ole edetty muttei ole edetty maksamiseen asti. maksamiseen asti. Ei maksettu. Ei maksettu. Jos vastauksesta löytyy arvot tiedoille Jos vastauksesta löytyy arvot tiedoille pmtq_paymentmethod pmtq_paymentmethod ja pmtq_amount: ja pmtq_amount: Tilaus on luotu ja maksutapa valittu, mutta Tilaus on luotu ja maksutapa valittu, mutta Maksuturvalla ei Maksuturvalla ei ole (vielä) tietoa, onko ole (vielä) tietoa, onko maksaminen onnistunut. maksaminen onnistunut. 01 Kyselyn suoritus epäonnistui Poikkeustilanne. Haetun tapahtuman haku epäonnistui Maksuturvasta. 10 Odottaa maksua, tilisiirto Asiakas on valinnut maksutavaksi tilisiirron ja maksua ei ole vielä todettu saapuneeksi. Toimitus käynnistetään yleensä vasta kun tapahtuman tila on 20 / maksettu. 11 Ei maksettu, maksun saapuminen Asiakas on siirtynyt tilisiirtosivulle ja on nähnyt maksun tiedot, epävarmaa mutta ei ole vahvistanut toimeksiantoa Maksuturvalle eikä näin ollen myöskään palannut verkkokauppaan tilauksen vahvistukseen.Tapahtumalle voi tulla maksu, jolloin se siirtyy tilaan 20 / maksettu ja toimituksen voi käynnistää. 15 Odottaa maksua, mutta toimitusvahvistus Asiakas on valinnut maksutavaksi tilisiirron ja maksua ei annettu ole vielä todettu saapuneeksi. Tilauksen toimitustieto on (Tyytyväisyystakuu) kuitenkin annettu. Yleensä toimitusta ei käynnistetä ellei maksua ole todettu maksetuksi (eli ellei se ole siirtynyt tilaan 20 / maksettu). Hyvitystä verkkokaupalle ei tehdä vaikka toimitus menisi perille asti ellei maksua ole todettu maksetuksi. 20 Maksettu mutta toimitusvahvistus on Asiakas on maksanut tilauksen Maksuturvan asiakasvarat antamatta -tilille, mutta toimitusvahvistusta ei ole vielä välitetty (Tyytyväisyystakuu) Maksuturvaan. Toimitus tulee käynnistää ja toimitustiedot tulisi välitää. 30 40 Maksettu, tilaus toimituksessa / Toimitus on kesken tai toimituksen jälkeinen karenssiaika on verkkokauppaa ei ole vielä hyvitetty kesken. Hyvitystä verkkokaupalle ei ole vielä tehty. Maksu on hyvitetty verkkokaupalle Maksu on hyvitetty verkkokaupalle. Maksu näkyy verkkokaupan ilmoittamalla tilillä pankkiyhteydestä riippuen muutaman arkipäivän sisällä. Tapahtuma on loppuun käsitelty. 91 Maksaja on peruuttanut tapahtuman Asiakas on tehnyt peruutuksen Maksuturvalle. Tapahtuma odottaa peruutusvahvistusta verkkokaupalta. Yleensä (Tyytyväisyystakuu) verkkokauppa peruuttaa tapahtuman vasta kuin mahdollinen tuotepalautus on vastaanotettu. Mikäli tuotetta ei ole ehditty lähettää, voi peruutuksen tehdä heti. Peruutuksen jälkeen rahat palautetaan asiakkaalle. 92 Maksaja on peruuttanut osan tapahtumasta Asiakas ehdottaa hinnan alennusta tilaukseen. (hinnan alennus) Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] / 129 58 / 129 Maksuturvan maksupalvelun integrointiohjeet (Tyytyväisyystakuu) Hinnan alennus odottaa vahvistusta verkkokaupalta. Mikäli tuotetta ei ole ehditty lähettää, voi hinnan alennuksen tehdä heti. Verkkokaupan hyväksynnän jälkeen sovittu summa palautetaan asiakkaalle. 93 Maksaja on peruuttanut osan tapahtumasta Asiakas ehdottaa hinnan alennusta ja joidenkin tuotteiden (hinnan alennus + tuotteiden palautus) (Tyytyväisyystakuu) palautusta. Peruutus odottaa vahvistusta verkkokaupalta. Yleensä verkkokauppa peruuttaa tapahtuman vasta kuin mahdollinen tuotepalautus on vastaanotettu. Mikäli tuotetta ei ole ehditty lähettää, voi peruutuksen vahvistaa heti. Verkkokaupan hyväksynnän jälkeen sovittu summa palautetaan asiakkaalle. 95 Maksaja on tehnyt reklamaation Maksaja on tehnyt reklamaation. Verkkokaupan on sovittava ostajan kanssa, mitä tilaukselle (Tyytyväisyystakuu) tehdään. Sen jälkeen ostaja voi peruuttaa reklamaation ja tapahtumalle voidaan tehdä valitun kaltainen peruutus tai tapahtuman voidaan antaa edetä normaalisti. 99 Peruutettu (Myyjä peruuttanut / hyväksynyt Olet tehnyt peruutuksen Maksuturvalle. Tapahtuma on ostajan peruutuksen) loppuun käsitelty. HUOM! suoramaksupalveluiden tapauksessa tämä EI kosketa pankkimaksuja. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 59 3.4.3.1.2 Toimituksen tilakoodien arvot (vain Tyytyväisyystakuupalveluille) Tilakoodi Lyhyt selite Kuvaus 00 Koodi vastaanotettu Maksuturva on vastaanottanut koodin, mutta toimituksen ei ole todettu edenneen. 10 Toimitettavana Toimituksen on todettu edenneen. Tämä tapahtuu joko tietyn ajan kuluttua (seurantakoodittomat) tai kuljetusyrityksen järjestlmästä tehdyn kyselyn (seurantakoodilliset) perusteella. 20 Odottaa noutoa Seurantakoodilla suoritetulla kyselyllä on saatu kuljetusyritykseltä vastaus, joka ilmaisee lähetyksen saapuneen toimipisteeseen vastaanottajan noudettavaksi. Tämä tila on myös kotiin kuljetettavilla toimituksilla, joiden tila ilmaisee, että pakettia ollaan toimittamassa perille. 80 Toimitettu Perillä. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] / 129 60 / 129 Maksuturvan maksupalvelun integrointiohjeet 3.5 Toimitustietojen hallinta Toimitustietojen hallinnan rajapintakuvaus, versio 2.1 Palvelun avulla voi hallita toimeksiannon toimitustietoja, eli lisätä, muuttaa tai poistaa toimitustietoja. Toimitustietoja ovat toimitustapa ja mahdollinen lähetystunniste. Lähetystunniste annetaan jos toimitustapana on kuljetusyrityksen kirjattu lähetys. Huomioithan, että nämä palvelut toimivat vain Tyytyväisyystakuuta hyödyntävien palveluiden kanssa. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 61 / 129 3.5.1 Toimitustietojen välityksen tiedot Tilaukseen liittyvä(t) lähetystunniste(et) tai toimitustiedot voidaan lähettää maksamisen jälkeen. Tiedot lähetetään osoitteeseen https://www.maksuturva.fi/addDeliveryInfo.pmt (tai http://test1.maksuturva.fi/addDeliveryInfo.pmt testiympäristössä) Kentän Kenttä nro Tiedon nimi Arvo input name= value= Muoto P/V 1. Lähetyksen versio pkg_version 0002 AN4 P 2. Verkkokaupan tunnus pkg_sellerid AN15 P 3. Maksun tunnus pkg_id AN20 P 4. Toimitustavan tunniste pkg_deliverymethodid AN5 P 5. Lisättävät toimitustiedot pkg_adddeliveryinfo AN50 P 7. Kaikki toimitustiedot annettu pkg_allsent Y/N AN1 P 8. Pakota päivitys pkg_forceupdate Y/N AN1 V 9. Vastauksen tyyppi pkg_resptype XML/HTML AN4 V 10. Paluuosoite pkg_return AN200 V 11. Tarkisteen laskentatapa pkg_hashversion AN10 P 12. Tarkiste pkg_hash AN128 P 13. Avaimen sukupolvi pkg_keygeneration N3 P Merkintä ANxx tarkoittaa, että kenttä sisältää enintään xx aakkosnumeerista merkkiä. P tarkoittaa pakollista tietoa ja V valinnaista. Minimipituus valinnaisten kenttien kohdalla ei tarkoita, että kyseisessä kentässä pitää aina olla sen mittainen merkkijono. Valinnainen kenttä voi uupua kokonaan pyynnöstä tai sen arvo voi olla tyhjä. Toki mikäli valinnainen tieto ei ole tyhjä, on se oltava vähintään minimipituuden mittainen. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 62 / 129 Maksuturvan maksupalvelun integrointiohjeet 3.5.2 Toimitustietojen muokkauksen tiedot Tilaukseen liittyvä(t) lähetystunniste(et) voidaan lähettää maksamisen jälkeen tai osana maksusanomaa. Tiedot lähetetään osoitteeseen https://www.maksuturva.fi/updateDeliveryInfo.pmt (tai http://test1.maksuturva.fi/updateDeliveryInfo.pmt testiympäristössä) Kentän Kenttä nro Tiedon nimi Arvo input name= value= Muoto P/V 1. Lähetyksen versio pkg_version 0002 AN4 P 2. Verkkokaupan tunnus pkg_sellerid AN15 P 3. Maksun tunnus pkg_id AN20 P 4. Toimitustavan tunniste pkg_deliverymethodid AN5 P 5. Lisättävät toimitustiedot pkg_adddeliveryinfo AN50 P 6. Poistettavat toimitustiedot pkg_remdeliveryinfo AN50 P 7. Kaikki toimitustiedot annettu pkg_allsent Y/N AN1 P 8. Pakota päivitys pkg_forceupdate Y/N AN1 V 9. Vastauksen tyyppi pkg_resptype XML/HTML AN4 V 10. Paluuosoite pkg_return AN200 V 11. Tarkisteen laskentatapa pkg_hashversion AN10 P 12. Tarkiste pkg_hash AN128 P 13. Avaimen sukupolvi pkg_keygeneration N3 P Merkintä ANxx tarkoittaa, että kenttä sisältää enintään xx aakkosnumeerista merkkiä. P tarkoittaa pakollista tietoa ja V valinnaista. Minimipituus valinnaisten kenttien kohdalla ei tarkoita, että kyseisessä kentässä pitää aina olla sen mittainen merkkijono. Valinnainen kenttä voi uupua kokonaan pyynnöstä tai sen arvo voi olla tyhjä. Toki mikäli valinnainen tieto ei ole tyhjä, on se oltava vähintään minimipituuden mittainen. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 63 / 129 3.5.3 Toimitustietojen poiston tiedot Tilaukseen liittyvä(t) lähetystunniste(et) voidaan lähettää maksamisen jälkeen tai osana maksusanomaa. Tiedot lähetetään osoitteeseen https://www.maksuturva.fi/deleteDeliveryInfo.pmt (tai http://test1.maksuturva.fi/deleteDeliveryInfo.pmt testiympäristössä) Kentän Kenttä nro Tiedon nimi Arvo input name= value= Muoto P/V 1. Lähetyksen versio pkg_version 0002 AN4 P 2. Verkkokaupan tunnus pkg_sellerid AN15 P 3. Maksun tunnus pkg_id AN20 P 6. Poistettavat toimitustiedot pkg_remdeliveryinfo AN50 P 7. Kaikki toimitustiedot annettu pkg_allsent Y/N AN1 P 8. Pakota päivitys pkg_forceupdate Y/N AN1 V 9. Vastauksen tyyppi pkg_resptype XML/HTML AN4 V 10. Paluuosoite pkg_return AN200 V 11. Tarkisteen laskentatapa pkg_hashversion AN10 P 12. Tarkiste pkg_hash AN128 P 13. Avaimen sukupolvi pkg_keygeneration N3 P Merkintä ANxx tarkoittaa, että kenttä sisältää enintään xx aakkosnumeerista merkkiä. P tarkoittaa pakollista tietoa ja V valinnaista. Minimipituus valinnaisten kenttien kohdalla ei tarkoita, että kyseisessä kentässä pitää aina olla sen mittainen merkkijono. Valinnainen kenttä voi uupua kokonaan pyynnöstä tai sen arvo voi olla tyhjä. Toki mikäli valinnainen tieto ei ole tyhjä, on se oltava vähintään minimipituuden mittainen. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 64 / 129 Maksuturvan maksupalvelun integrointiohjeet 3.5.4 Lähetystunnisteiden välityksen vastaussanoman tiedot Kentän Kenttä nro Tiedon nimi Arvo input name= value= pkg_version 0001 AN4 P AN15 P AN20 P AN2 P AN300 P AN128 P 1. Lähetyksen versio 2. Verkkokaupan tunnus pkg_sellerid 3. Maksun tunnus pkg_id 4. Vastauskoodi pkg_resultcode 5. Vastausteksti pkg_resulttext 6. Vastauksen tarkiste pkg_hash Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Muoto P/V Maksuturvan maksupalvelun integrointiohjeet 3.5.5 Kenttien selitteet Kentän Kenttä Selite nro 1. Lähetyksen versio Lähetystunnisteiden lähettämiseen käytetyn ”sanoman” sisällön määrittelyversio. 2. Verkkokaupan Suomen Maksuturva Oy:n verkkokaupan tunnistamista varten antama tunnus. tunnus 3. Maksun tunnus Verkkokaupan maksulle antama yksilöivä tunnus. 4. Toimitustavan Toimitustavan tunniste. Tunnisteet löytyvät kohdasta Toimitustapojen tunnisteet. tunniste 5. Lisättävä Aiemmin toimitettuun maksuun liittyvä toimitustieto. toimitustieto 6. 7. Poistettava Aiemmin toimitettua toimitustietoa poistettaessa, tai päivitettäessä, tässä kentässä toimitetaan toimitustieto poistettava toimitustieto. Kaikki Onko kaikkien maksuun liittyvien lähetysten lähetystunnisteet toimitettu Suomen Maksuturva toimitustiedot Oy:lle. Arvona oltava”Y”, jos sanoma sisältää kaikki maksuun liittyvät lähetystunnisteet. annettu 8. Pakota päivitys 9. Vastauksen tyyppi Määrittää missä muodossa vastaussanoma tehdään. Vaihtoehdot ovat HTML ja XML. Oletuksena HTML. 10. Paluuosoite Jos vastauksen tyyppi on HTML, niin voidaan määrittää paluuosoite. Jos paluuosoite on määritetty, niin vastauksen tiedot tullaan välittämään suoraan tähän osoitteeseen lisättynä osoitteseen ns. ”querystring” – parametreina. 11. 12. Tarkisteen Tarkisteen laskennassa käytetty algoritmi laskentatapa (algoritmin nimi, katso tarkempi kuvaus Rajapintojen Integrointiohjeesta) Tarkiste Sanoman kentistä ja verkkokaupan salaisesta avaimesta laskettu tarkiste. Tarkiste lasketaan seuraavista kentistä: pkg_id pkg_deliverymethodid pkg_allsent 13. Avaimen sukupolvi Verkkokaupan salaisen avaimen sukupolvinumero. 14. Vastauskoodi Kertoo sanoman käsittelyn lopputuloksen. Arvot ja niiden selitteet kohdassa Vastauskoodin arvot. Kenttä sisältää ensimmäisen vastaantulleen virheen koodin, mutta vastausteksti kentässä voi olla virhekuvaus myös muista virheistä. 15. Vastausteksti Erittelee virhetapauksessa virheen syyn, mikäli sovelluksella tiedossa. Esim mitkä seurantakoodeista eivät läpäisseet muototarkistusta, tai mitkä seurantakoodit löytyivät jo kannasta. Syntaksi on muotoa virhekoodi: selite, esim 30: JJFI00000012345123456,30:JJFI00000012345123457 16. Vastauksen tarkiste Sanoman kentistä ja verkkokaupan salaisesta avaimesta laskettu tarkiste. Tarkiste lasketaan vain, jos pyydetty toiminto suoritettiin onnistuneesti. Tarkisteen laskennassa käytetään avain- ym. tietoja sekä algoritmia kuin sisään tulevalla sanomalla. Tarkiste lasketaan kentistä: pkg_sellerid pkg_id pkg_resultcode Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 65 / 129 66 / 129 Maksuturvan maksupalvelun integrointiohjeet 3.5.6 Toimitustapojen tunnisteet Toimitustapa Lyhyt kuvaus ITELL Selite Itellan kirjattu lähetys Tuotteet toimitetaan Itellan pakettina tai kirjattuna kirjeenä. Toimitustiedon voi antaa heti kun paketin lähetystunniste on tiedossa, toimitukseen liittyy aina lähetystunniste. Lähetystunniste on Itellalta saatu paketin tunnus, jolla voi seurata paketin toimitusta Itellan lähetyksenseurantapalvelusta. MATHU Matkahuollon kirjattu lähetys Tuotteet toimitetaan Matkahuollon pakettina. Toimitustietojen antaminen kuten Itellan osalta. KAUKO Kaukokiidon kirjattu lähetys Tuotteet toimitetaan Kaukokiidon pakettina. Toimitustietojen antaminen kuten Itellan osalta. TRANS Transpointin kirjattu lähetys Tuotteet toimitetaan Transpointin pakettina. Toimitustietojen antaminen kuten Itellan osalta. KIITO Kiitolinjan kirjattu lähetys Tuotteet toimitetaan Kiitolinjan pakettina. Toimitustietojen antaminen kuten Itellan osalta. MYPAC MyPack:n kirjattu lähetys Tuotteet toimitetaan MyPack:n pakettina. Toimitustietojen antaminen kuten Itellan osalta. DBSCH DB Schenkerin kirjattu lähetys Tuotteet toimitetaan DB Schenkerin pakettina. Toimitustietojen antaminen kuten Itellan osalta. FEDEX FedEx:n kirjattu lähetys Tuotteet toimitetaan FedEx:n pakettina. Toimitustietojen antaminen kuten Itellan osalta. DHLDP DHL:n kirjattu lähetys Tuotteet toimitetaan DHL:n pakettina. Toimitustietojen antaminen kuten Itellan osalta. TNTNV TNT:n kirjattu lähetys Tuotteet toimitetaan TNT:n pakettina. Toimitustietojen antaminen kuten Itellan osalta. UPSAM UPS:n kirjattu lähetys Tuotteet toimitetaan UPS:n pakettina. Toimitustietojen antaminen kuten Itellan osalta. UNREG Kirjaamaton kirje Tuotteet toimitetaan kirjaamattomana kirjeenä (tavallinen postin kirje). Toimitukseen ei liity lähetystunnisteita. Toimitustieto annetaan vasta kun kirje on lähetetty. PICKU Nouto Asiakas noutaa tuotteet verkkokaupasta / verkkokaupan noutopisteestä. Toimitukseen ei liity lähetystunnisteita. Toimitustieto annetaan vasta kun asiakas on noutanut tilauksensa. ODLVR Oma kuljetus Tuotteet toimitetaan asiakkaalla verkkokaupan omalla kuljetuksella. Toimitukseen ei liity lähetystunnisteita. Toimitustieto annetaan vasta kun tilaus on toimitettu perille. SERVI Palvelun suoritus Asiakkaalle suoritetaan palvelu. Tilaukseen ei liity tuotteen toimitusta eikä näin ollen lähetystunnisteitakaan. Palvelun suoritustieto toimitustietona annetaan vasta kun palvelu on suoritettu asiakkaalle. ELECT Sähköinen toimitus Tuote on sähköisessä muodossa toimitettava (esim. sähköpostilla), eli se on asiakkaalla perillä heti toimituksen jälkeen. Toimitukseen ei liity lähetystunnisteita. Toimitustieto annetaan kun tuote on toimitettu / lähetetty. UNREF Ulkomainen kirjaamaton kirje Tuotteet toimitetaan kirjaamattomana kirjeenä ulkomaille. Toimitukseen ei liity lähetystunnisteita. Toimitustieto annetaan vasta kun kirje on lähetetty. Toimitusaika on paljon pidempi kuin tavanomaisella kirjeellä (UNREG). Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet UNRDL Kirjaamaton lähetys Tuotteet toimitetaan kirjaamattomana lähetyksenä (esim. tavallinen postin kirje). Toimitukseen ei liity lähetystunnisteita. Toimitustieto annetaan vasta kun kirje/paketti on lähetetty. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 67 / 129 68 / 129 Maksuturvan maksupalvelun integrointiohjeet 3.5.7 Vastauskoodin arvot Vastauskoodi Lyhyt kuvaus Selite 00 Ok Sanoma käsitelty ok. 10 Tapahtumaa Poikkeustilanne. Annetuilla tiedoilla ei löydy maksutapahtumaa. ei löydy 11 Suoritus Poikkeustilanne. Sanoman suoritus epäonnistui. epäonnistui 12 Ei palvelua Poikkeustilanne. Välitetyllä verkkokaupan tunnuksella ei löytynyt palvelua. 20 Muotovirheitä Lisättävässä toimitustiedossa muotovirheitä. Vastaustekstissä on lisätietoa virheestä. 30 On jo Toimitustieto on jo välitetty. 31 Toimitustieto Poikkeustilanne. Poistettavaa toimitustietoa ei löytynyt. ei löydy 40 41 Väärä Välitetty toimitustapakoodi ei vastaa aiemmin välitettyjen toimitustapojen koodia. Yhteen toimitustapa tapahtumaan voi liittyä vain yhdenlainen toimitustapa. Toimitustapa Välitetty toimitustapakoodi vastaa toimitustapaa, mitä ei ole kytketty palvelulle käyttöön. ei sallittu 42 Pakota Yritetään lisätä, poistaa tai päivittää toimitustapoja sellaiselle tapahtumalle, jolla on aiemmin päivitys vahvistettu kaikki toimitustavat annetuksi eikä sanomassa ole ”pkg_forceupdate” arvona ”Y”. vaadittu 99 Muita virheitä Välitetyissä tiedoissa muita virheitä. Vastaustekstissä on lisätietoa virheestä. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 3.6 Palautusten ja peruutusten hallinta Maksutapahtuman palautusten ja peruutusten hallinta rajapintakuvaus, versio 5.0 Palvelun avulla voi tehdä tai hyväksyä rahapalautuksia tilauksiin. Huomioithan, että tämä palvelu toimii vain Tyytyväisyystakuuta hyödyntävien palveluiden kanssa. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 69 / 129 70 / 129 Maksuturvan maksupalvelun integrointiohjeet 3.6.1 Muutokset Muutospvm Dokumentin Muutos versio Helmikuu 4.0 2011 MAKSUN PERUUTUKSEN TIEDOT (IN) Uusia tietoja: - pmtc_action (CANCEL) Osaperuutukseen vaatimat uudet tiedot: - Peruutuksen tyyppi (pmtc_canceltype) - Peruutettava rahamäärä (pmtc_cancelamount) Uusia tietoja pyynnön tarkisteessa: - pmtc_action (CANCEL) - pmtc_version - pmtc_canceltype - pmtc_cancelamount (jos canceltype = PARTIAL_REFUND / PARTIAL_REFUND_AND_RETURN_OF_DELIVERIES) MAKSUN PERUUTUKSEN VASTAUSSANOMAN TIEDOT (OUT) Uusia kenttiä tarkisteessa: - pmtc_action (CANCEL) - pmtc_version - Muutettu kenttien järjestystä tarkisteessa. Uusi vastauskoodi 31: Peruutustiedot eivät täsmää Syyskuu 2013 5.0 MAKSUN PERUUTUKSEN TIEDOT (IN) Uusia tietoja (Luotetun kauppiaan palveluille): - Palautustili (pmtc_payeribanrefund) - HUOM! Käytössä vain mikäli verkkokaupan kanssa erikseen sovittu asiasta! - Peruutuksen kuvaus (pmtc_canceldescription) - Peruutuksen syykoodi (pmtc_cancelreason) Uusia tietoja pyynnön tarkisteessa: - pmtc_payeribanrefund MAKSUN PERUUTUKSEN VASTAUSSANOMAN TIEDOT (OUT) Uusia kenttiä tarkisteessa: - errors –elementti, joka erittelee tiedoissa olleet virheet Uusi vastauskoodi 90: Syöttötiedoissa oli virheitä Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 71 3.6.2 Maksutapahtuman muutoksen tiedot / 129 Maksutapahtuman muuttaminen on sallittua, kun tapahtuma ei ole vielä edennyt siihen asti, että rahoja ollaan tilittämässä tai ollaan jo tilitetty verkkokaupalle. Verkkokauppa välittää tapahtuman peruutuksen tiedot <form>-tietoryhmässä piilomuuttujina (<input type=hidden>) osoitteeseen https://www.maksuturva.fi/PaymentCancel.pmt (tai http://test1.maksuturva.fi/PaymentCancel.pmt testiympäristössä) Kentän Kenttä numero 1. Toiminnon Tiedon nimi Arvo input name= value= Muoto P/V pmtc_action CANCEL AN6 P pmtc_version 0005 AN4 P AN15 P pmtc_id AN20 P pmtc_amount N17 P pmtc_currency AN3 P pmtc_canceltype FULL_REFUND AN40 P tunnus 2. Sanoman versio 3. Verkkokaupan pmtc_sellerid tunnus 4. Maksun tunnus 5. Maksun rahamäärä 6. Maksun valuutta 7. Peruutuksen tyyppi PARTIAL_REFUND PARTIAL_REFUND_AND_RETURN_OF_DELIVERIES 8. Peruutettava pmtc_cancelamount esim. 15,00 N17 pmtc_payeribanrefund IBAN-tilinumero AN36 P/V rahamäärä 9. Palautustili V HUOM! Käytössä vain mikäli verkkokaupan kanssa erikseen sovittu asiasta! 10. Palautuksen pmtc_canceldescription AN500 V pmtc_cancelreason AN5 V pmtc_resptype XML AN4 P AN10 P AN128 P selite 11. Palautuksen syykoodi 12. Vastauksen tyyppi 13. Tarkistetiedon pmtc_hashversion versio 14. Tarkiste pmtc_hash 15. Avaimen pmtc_keygeneration N3 P sukupolvi Merkintä ANxx tarkoittaa, että kenttä sisältää enintään xx aakkosnumeerista merkkiä. P tarkoittaa pakollista tietoa ja V valinnaista. P/V tarkoittaa ehdollisesti pakollista tietoa (esim. kaksi toisillensa vaihtoehtoista tietoa, kuten pmt_row_price_grossN ja pmt_row_price_netN). Minimipituus valinnaisten kenttien kohdalla ei tarkoita, että kyseisessä kentässä pitää aina olla sen mittainen merkkijono. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 72 / 129 Maksuturvan maksupalvelun integrointiohjeet Valinnainen kenttä voi uupua kokonaan pyynnöstä tai sen arvo voi olla tyhjä. Toki mikäli valinnainen tieto ei ole tyhjä, on se oltava vähintään minimipituuden mittainen. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 3.6.2.1 Kenttien selitteet - Maksun peruutuksen tiedot Kentän Kenttä Selite numero 1. Toiminnon tunnus Kutsuttavan toiminnon tunnus (CANCEL). 2. Sanoman versio Tapahtuman peruutussanoman sisällön määrittelyversio. 3. Verkkokaupan tunnus Suomen Maksuturva Oy:n verkkokaupalle tunnistamista varten antama tunnus. 4. Maksun tunnus Verkkokaupan maksulle antama yksilöivä tunnus. Täsmättävä alkuperäisen maksun kanssa. 5. Maksun rahamäärä Alkuperäisen maksun summa. Summa tulee esittää aina kahden desimaalin tarkkuudella. Desimaalierottimena käytetään pilkkua esim. 94,80 6. Maksun valuutta Alkuperäisessä maksussa käytetty valuutta. 7. Peruutuksen tyyppi Kertoo onko kyseessä • Koko tilauksen peruutus (FULL_REFUND) • Hinnan korjaus (PARTIAL_REFUND) • Osapalautus (PARTIAL_REFUND_AND_RETURN_OF_DELIVERIES) 8. Palautettava/hyvitettävä Rahamäärä, minkä verran ostajalle halutaan palauttaa/hyvittää. rahamäärä Huomioitan, että tämä tieto annetaan vain, kun peruutuksen tyyppi ei ole koko tilauksen peruutus (FULL_REFUND). 9. Palautustili Mikäli verkkokaupalla on käytössään on erikseen tilattavissa oleva palvelu, jossa verkkokaupan on mahdollista tehdä palautukset ja muutokset siten, että Maksuturva ei ole ollenkaan yhteydessä ostajaan (eikä ostajalla ole käytössään Verkko-ostajan palvelua), niin verkkokaupan saattaa olla tarpeen välittää peruutuksen yhteydessä tilinumero palautusta varten. Tilinumeroa tarvitsee välittää vain mikäli tilaus maksettiin pankissa. Eli ts. kortti-, laksuja erämaksutapahtumien tapauksessa tilinumeroa ei tarvitse välittää. HUOM! Käytössä vain mikäli verkkokaupan kanssa erikseen sovittu asiasta! 10. Palautuksen selite Valinnainen seliteteksti palautukselle. Voidaan näyttää ostajalle. 11. Palautuksen syykoodi Valinnainen syykoodi palautukselle. Voidaan näyttää ostajalle. Sallitut arvot: Syykoodi Selite NOTDE Tilausta ei ole toimitettu WSIZE Tuote on väärän kokoinen INCOR Toimitus ei vastaa tilausta DEFEC Tuote on rikki OUTOF Tuote on loppunut OTHER Muu syy 12. Vastauksen tyyppi Ainoastaan XML-tyyppinen vastaus on tuettuna versiosta 0005 alkaen. 13. Tarkistetiedon versio Tarkisteen laskennassa käytetty laskentaversio (algoritmin nimi, katso tarkempi kuvaus Rajapintojen Integrointiohjeesta) 14. Tarkiste Sanoman kentistä ja verkkokaupan salaisesta avaimesta laskettu tarkiste. Tarkiste lasketaan tiedoista: • pmtc_action • pmtc_version Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 73 / 129 74 / 129 Maksuturvan maksupalvelun integrointiohjeet • pmtc_sellerid • pmtc_id • pmtc_amount • pmtc_currency • pmtc_canceltype • pmtc_cancelamount (jos peruutuksen tyyppi on PARTIAL_REFUND / PARTIAL_REFUND_AND_RETURN_OF_DELIVERIES) • pmtc_payeribanrefund (jos annettu) Tarkemmat ohjeet tarkisteen laskentaan 15. Avaimen sukupolvi Verkkokaupan salaisen avaimen sukupolvinumero. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 75 3.6.3 Maksun peruutuksen vastaussanoman tiedot Kentän Kenttä numero 1. Toiminnon Tiedon nimi Arvo input name= value= Muoto P/V pmtc_action CANCEL AN6 P pmtc_version 0005 AN4 P pmtc_sellerid AN15 P AN20 P AN2 P AN100 P AN128 P V tunniste 2. Sanoman versio 3. Verkkokaupan tunnus 4. Maksun tunnus pmtc_id 5. Vastauskoodi pmtc_returncode 6. Vastausteksti pmtc_returntext 7. Tarkiste pmtc_hash 8. Syöttövirheiden errors erittely Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] / 129 76 / 129 Maksuturvan maksupalvelun integrointiohjeet 3.6.3.1 Kenttien selitteet - Maksun peruutuksen vastaussanoman tiedot Kentän Kenttä Selite numero 1. Toiminnon CANCEL tunniste 2. Sanoman Tapahtuman peruutussanoman sisällön määrittelyversio. versio 3. Verkkokaupan Suomen Maksuturva Oy:n verkkokaupalle tunnistamista varten antama tunnus. tunnus 4. Maksun tunnus Verkkokaupan maksulle antama yksilöivä tunnus. Täsmättävä alkuperäisen maksun tunnukseen. 5. Vastauskoodi Kertoo peruutuksen onnistumisen. Vastauskoodien arvot ja selitteet löytyvät kohdasta Vastauskoodien arvot 6. Vastausteksti Kuvaa lyhyesti peruutuksen epäonnistumisen syyn. Peruutuksen onnistuessa tyhjä. 7. Tarkiste Sanoman kentistä ja verkkokaupan salaisesta avaimesta laskettu tarkiste. Tarkisteen laskennassa käytetään samoja versio-, avain- ym. tietoja kuin sisään tulevalla sanomalla. Tarkiste lasketaan tiedoista: • pmtc_action • pmtc_version • pmtc_sellerid • pmtc_id • pmtc_returntext • pmtc_returncode Tarkemmat ohjeet tarkisteen laskentaan. 8. Syöttövirheiden XML-rakenne, joka listaa mahdolliset syöttötiedoissa olleet virheet kenttäkohtaisesti. erittely Vastauskoodien arvot Vastauskoodi Lyhyt selite Kuvaus 00 Ok Peruutus on otettu onnistuneesti vastaan. 20 Tapahtumaa ei löytynyt Poikkeustilanne. Tapahtumaa ei löytynyt eikä peruutusta voitu tehdä. 30 Maksu on hyvitetty tai Tapahtumaa ei voi perua koska se on jo käsitelty loppuun joko hyvityksen tai tapahtuma peruutettu peruutuksen muodossa. Peruutustiedot eivät Myyjän ja ostajan antamat peruutustiedot eivät täsmää. 31 täsmää 90 Syöttötiedoissa oli Syöttötiedoissa oli virheitä, erittely löytyy vastauksen elementistä ”errors” virheitä 99 Peruutuksen suoritus Poikkeustilanne. Peruutuksen käsittely epäonnistui. epäonnistui Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 3.7 Tilitysraporttien hakeminen Tilitysraporttien hakemisen rajapintakuvaus, versio 1.1.1 Tämä palvelu mahdollistaa tilitysraportoinnin integroinnin verkkokauppaan. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 77 / 129 78 / 129 Maksuturvan maksupalvelun integrointiohjeet 3.7.1 Muutokset Muutospvm Dokumentin Muutos versio Maaliskuu 1.0 Ensimmäinen versio 1.1 Lisätty loogista kuvausta tiedoista. 1.1.1 Lisätty ohjeistusta ja tarkennuksia. 2012 Kesäkuu 2012 Syyskuu 2013 Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 79 / 129 3.7.2 Raportin pyynnön tiedot Verkkokauppa välittää maksun tiedot <form>-tietoryhmässä piilomuuttujina (<input type=hidden>) Tiedot lähetetään osoitteeseen https://www.maksuturva.fi/GetCompensationsByTimeInterval.pmt (tai http://test1.maksuturva.fi/GetCompensationsByTimeInterval.pmt testiympäristössä) Kentän Kenttä numero 1. Toiminnon Tiedon nimi Arvo input name= value= Muoto Minimipituus P/V gc_action GET_COMPENSATIONS AN50 4 P gc_version 0001 AN4 4 P AN15 tunniste 2. Sanoman versio 3. Verkkokaupan gc_sellerid P tunnus 4. Alkupäivä gc_begindate dd.MM.yyyy AN10 10 P 5. Loppupäivä gc_enddate dd.MM.yyyy AN10 10 P 6. Tarkistetiedon gc_hashversion esim. SHA-256 AN10 P N3 P versio 7. Avaimen gc_keygeneration esim. 1 sukupolvi 8. Tarkiste gc_hash Tarkiste lasketaan kaikista muista mukana olleista AN128 32 P tiedoista ja salaisesta avaimesta. Katso tarkemmat ohjeet Tilitysraportin tarkistekappaleesta. Merkintä ANxx tarkoittaa, että kenttä sisältää enintään xx aakkosnumeerista merkkiä. P tarkoittaa pakollista tietoa ja V valinnaista. Minimipituus valinnaisten kenttien kohdalla ei tarkoita, että kyseisessä kentässä pitää aina olla sen mittainen merkkijono. Valinnainen kenttä voi uupua kokonaan pyynnöstä tai sen arvo voi olla tyhjä. Toki mikäli valinnainen tieto ei ole tyhjä, on se oltava vähintään minimipituuden mittainen. Huomioithan, että alkupäivän ja loppupäivän välinen ero saa olla korkeintaan yksi kuukausi! Testaamisesta Tällä hetkellä testaaminen on mahdollista vain siinä tapauksessa, että Maksuturva päivittää testitapahtumia manuaalisesti tilitetyiksi. Testaaminen on tehtävä verkkokauppakohtaisilla testitunnuksilla. Sinun kannattaa joka tapauksessa kysyä lisää XML-raportin testaamisesta, koska se edellyttää aina toimia myös Maksuturvalta testiympäristössä. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 80 / 129 Maksuturvan maksupalvelun integrointiohjeet 3.7.3 Tilitysraportin tiedot Vastaussanoma on XML-muotoinen tilitysraportti. Tiedosto on UTF-8 -koodattu. Vastaussanoma on kuvattu XML Schemalla: https://www.maksuturva.fi/smtschema/ GetCompensationsResponse.xsd Jos vastaus kertoo virheestä, se EI sisällä kaikkia pakollisia tietoja. Muita vastauksen tietoja voi odottaa vain jos vastauskoodi eli resultCode on 00. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 3.7.3.1 Tilitysraportin tietojen looginen kuvaus Kustakin tilityserästä on seuraavat tiedot: • • • • • • • erän tunniste erän tilityspäivä erän viitenumero, jolla löytyy kaupan tiliotteelta erän maksuista laskettu verkkokaupan alun perin odottama bruttosumma todellinen tilitettävä nettosumma, joka on: brutto – palautukset – Maksuturvan palkkiot maksuturvan ottama palkkiosumma tilauksista ostajille palautettu summa Kustakin tilityserän sisältävästä tilauksesta on seuraavat tiedot: • • • • • tilausnumero (pmt_orderid) tilaukselle alunperin annettu viitenumero (pmt_reference) verkkokaupan maksulle antama yksilöivä tunniste (pmt_id) tilauksesta verkkokaupan alun perin odottama bruttosumma todellinen tilitettävä nettosumma, joka on: brutto – palautus – Maksuturvan (ja mahdollisen kauppapaikan) palkkiot • Maksuturvan (ja mahdollisen kauppapaikan) yhteensä tilauksesta ottama palkkiosumma • tilauksesta ostajille palautettu summa Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 81 / 129 82 / 129 Maksuturvan maksupalvelun integrointiohjeet 3.7.3.2 Tilitysraportin tarkiste Vastauksen tarkiste eli XML:n elementti hash lasketaan seuraavista vastauksen tiedoista: • • • • • • • version timestamp sellerId resultCode hashVersion keyGeneration salainen avain (joka ei sisälly vastaukseen) Katso tarkemmat ohjeet Tarkisteen laskenta-kappaleesta. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 83 3.7.3.3 Tilitysraportin vastauksen XML Sisältö avautuu parhaiten alla näkyvän esimerkin kautta. Esimerkki vastaussanomasta: <?xml version="1.0" encoding="UTF-8"?> <getCompensationsResponse> <version>0001</version> <timestamp>2010-05-30T09:30:10+02:00</timestamp> <sellerId>ABCD1234</sellerId> <resultCode>00</resultCode> <resultText>OK</resultText> <hashVersion>SHA-256</hashVersion> <keyGeneration>001</keyGeneration> <hash>e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855</hash> <compensations> <compensation> <compensationCode> tästä löytyy tieto, jos kyseessä on tilityserä (compensationType = BUNDLE), eikä yksittäisen tilauksen tilitys. </compensationCode> <compensationType> SINGLE = yksittäisen tapahtuman tilitys, BUNDLE = tilityserä </compensationType> <compensationDate>2010-05-30T00:00:00+02:00</compensationDate> <reference>12345123451234512345</reference> <grossAmount> tilityserän tilausten yhteenlaskettu bruttosumma, jota kauppias pyysi maksettavaksi alunperin </grossAmount> <netAmount>todellinen tilitetty summa</netAmount> <refundedAmount>todellinen näistä tilauksista ostajille palautettu summa</refundedAmount> <commission>maksuturvan ja muiden osapuolten välistä ottama palkkio</commission> <orders> ... tässä alla vain yksi order, jos käytössä on tapahtumakohtainen tilitys eikä koontitilitykset. <order> <bundleCode>valinnainen, mukana jos maksu kuuluu koontitilitykseen</bundleCode> <orderNumber>kauppiaan alun perin antama tilausnumero</orderNumber> <originalReference>kauppiaan tapahtumalle antama viite (pmt_reference)</ originalReference> <paymentId>kauppiaan tapahtumalle antama yksilöivä tunnus (pmt_id)</paymentId> <sellerGrossAmount> Kauppiaan pyytämä brutto (kauppahinta + kauppiaan toimitus-/käsittelykulut) = pmt_amount + pmt_sellercosts </sellerGrossAmount> <sellerNetAmount> Kauppiaan netto (kauppiaalle tilitetty rahamäärä) </sellerNetAmount> <refundedAmount> Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] / 129 84 / 129 Maksuturvan maksupalvelun integrointiohjeet todellinen tilauksesta ostajalle palautettu summa </refundedAmount> <commission> maksuturvan ja muiden osapuolten ottama palkkiot yhteensä (edellisten kenttien erotus) </commission> <buyerPaymentDatetime>2010-05-30T09:30:10+02:00</buyerPaymentDatetime> </order> </orders> </compensation> <compensation> tässä voi olla monta tilitystä peräkkäin ja kunkin kaikki tapahtumat sisällä </compensation> </compensations> </getCompensationsResponse> Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 85 3.8 Palvelun käyttöönotto (verkkokauppaohjelmistontarjoajille) / 129 Maksuturva-palvelun käyttöönoton rajapintakuvaus, versio 1.1 Huomioithan, että tämä palvelu on tarkoitettu verkkokauppaohjelmistontarjoajien käyttöön, jotka haluavat tehdä Maksuturva-palvelun tilaamisesta saumattoman kokemuksen integroimalla Maksuturvapalvelun käyttöönoton verkkokauppaohjelmiston hallintapaneeliin tai vastaavalle hallintasivustolle. Toisin sanoen yksittäinen verkkokauppa ei hyödy tämän palvelun käyttöönotosta mitenkään. Tämän palvelun käyttöön vaaditaan myös verkkokauppaohjelmistotoimittaja-kohtainen tunnus, joka eroaa huomattavasti verkkokaupan tunnuksesta, jota käytetään esim. Maksamisen rajapinnassa. Palvelun avulla verkkokauppaohjelmisto voi välittää verkkokaupan tiedot haluamaltaan osin Maksuturvalle nopeuttaakseen ja helpottaakseen verkkokaupan Maksuturva/eMaksutpalvelun tilausprosessia ja palvelun käyttöönottoa. Verkkokauppias täyttää / täydentää palvelun käyttöönottolomakkeen tarvittavilta osin ja vahvistaa eli allekirjoittaa tilauksensa joko pankkien tarjoamalla Tupas-allekirjoituksella tai pyytämällä paperisen sopimuksen allekirjoitettavaksi. Palvelun vastaussanoma kertoo tilauksen onnistumisesta seuraavilla tasoilla: • Luotiin uusi asiakkuus ja perustettiin uusi palvelu • Olemassa olevan asiakkuuden alle perustettiin uusi palvelu • Uutta palvelua ei voitu perustaa. Vastauksessa olevat virhekoodi ja selite kertovat tarkemman syyn. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 86 / 129 Maksuturvan maksupalvelun integrointiohjeet 3.8.1 Palvelun käyttöönoton tiedot Verkkokauppaohjelmisto välittää verkkokauppayrityksen, verkkokaupan ja Maksuturva-palvelun tiedot POST-metodia käyttäen <form>-tietoryhmässä piilomuuttujina (<input type=hidden>) . Tiedot lähetetään osoitteeseen https://www.maksuturva.fi/MerchantSubscription.pmt (tai http://test1.maksuturva.fi/MerchantSubscription.pmt testiympäristössä) Kentän Kenttä numero Tiedon nimi Arvo input name= value= 1. Palvelun käyttöönoton versio 2. Verkkokauppapalvelun tarjoajan srv_webstoreserviceid srv_version Muoto Minimipituus P/V 0002 AN4 4 P AN15 1 P AN15 9 V AN80 1 V AN80 1 V tunnus 3. Verkkokauppayrityksen y-tunnus srv_businessid 4. Verkkokauppayrityksen nimi srv_businessname 5. Verkkokauppayrityksen srv_marketingname srv_businesswww AN200 4 V srv_businessemail AN80 4 V srv_businessphone AN40 1 V srv_businessfax AN40 1 V AN30 18 V AN80 1 V AN200 4 P AN100 1 V markkinointinimi 6. Verkkokauppayrityksen wwwosoite 7. Verkkokauppayrityksen sähköpostiosoite 8. Verkkokauppayrityksen puhelinnumero 9. Verkkokauppayrityksen faksinumero 10. Verkkokaupan oletustilinumero srv_webstoreiban 11. Verkkokaupan nimi srv_webstorename 12. Verkkokaupan www-osoite srv_webstorewww 13. Verkkokaupan asiakaspalvelun srv_webstorecustomerservice srv_businessaddress AN100 5 V srv_businesspobox AN10 4 V srv_businesspostalcode AN5 5 V srv_businesscity AN40 1 V AN2 2 V AN100 5 V yhteystieto 14. Verkkokauppayrityksen katuosoite 15. Verkkokauppayrityksen postilokero 16. Verkkokauppayrityksen postinumero 17. Verkkokauppayrityksen postitoimipaikka 18. Verkkokauppayrityksen maa srv_businesscountrycode 19. Verkkokauppayrityksen srv_billingaddress srv_billingpobox AN10 4 V srv_billingpostalcode AN5 5 V srv_billingcity AN40 1 V laskutuskatuosoite 20. Verkkokauppayrityksen laskutuspostilokero 21. Verkkokauppayrityksen laskutuspostinumero 22. Verkkokauppayrityksen laskutuspostitoimipaikka Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 23. Verkkokauppayrityksen 87 srv_billingcountrycode AN2 2 V AN100 5 V AN10 4 V AN5 5 V AN40 1 V AN2 2 V AN80 1 V laskutusmaa 24. Verkkokaupan katuosoite srv_webstoreaddress 25. Verkkokaupan postilokero srv_webstorepobox 26. Verkkokaupan postinumero srv_webstorepostalcode 27. Verkkokaupan postitoimipaikka srv_webstorecity 28. Verkkokaupan maa srv_webstorecountrycode 29. Verkkokauppayrityksen srv_contactpersonname srv_contactpersonemail AN80 4 V srv_contactpersonphone AN40 1 V srv_contactpersonmobile AN40 1 V srv_contactpersonfax AN40 1 V srv_billingpersonname AN80 1 V srv_billingpersonemail AN80 4 V srv_billingpersonphone AN40 1 V srv_billingpersonmobile AN40 1 V srv_billingpersonfax AN40 1 V srv_webstorepersonname AN80 1 V srv_webstorepersonemail AN80 4 V srv_webstorepersonphone AN40 1 V srv_webstorepersonmobile AN40 1 V srv_webstorepersonfax AN40 1 V srv_paymentmethodinfo AN200 1 V srv_deliverymethodinfo AN200 1 V yhteyshenkilön nimi 30. Verkkokauppayrityksen yhteyshenkilön sähköpostiosoite 31. Verkkokauppayrityksen yhteyshenkilön puhelinnumero 32. Verkkokauppayrityksen yhteyshenkilön matkapuhelinnumero 33. Verkkokauppayrityksen yhteyshenkilön faksinumero 34. Verkkokauppayrityksen laskutusyhteyshenkilön nimi 35. Verkkokauppayrityksen laskutusyhteyshenkilön sähköpostiosoite 36. Verkkokauppayrityksen laskutusyhteyshenkilön puhelinnumero 37. Verkkokauppayrityksen laskutusyhteyshenkilön matkapuhelinnumero 38. Verkkokauppayrityksen laskutusyhteyshenkilön faksinumero 39. Verkkokaupan teknisen yhteyshenkilön nimi 40. Verkkokaupan teknisen yhteyshenkilön sähköpostiosoite 41. Verkkokaupan teknisen yhteyshenkilön puhelinnumero 42. Verkkokaupan teknisen yhteyshenkilön matkapuhelinnumero 43. Verkkokaupan teknisen yhteyshenkilön faksinumero 44. Verkkokaupan Maksuturvamaksutavat 45. Verkkokaupan Maksuturvatoimitustavat Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] / 129 88 / 129 46. Maksuturvan maksupalvelun integrointiohjeet Verkkokaupan Maksuturva- srv_servicebegindate dd.mm.yyyy AN10 10 V AN10 5 V AN2000 1 V AN4 3 V palvelun voimaantulopäivä 47. Kampanjakoodi srv_campaigncode 48. Lisätietoa tilauksesta srv_additionalinformation 49. Vastauksen tyyppi srv_resptype POST 50. Ok –paluuosoite srv_okreturn AN200 11 P 51. Virhe –paluuosoite srv_errorreturn AN200 11 V 52. Peruutus-paluuosoite srv_cancelreturn AN200 11 V 53. Tarkisteen laskentamerkistö srv_charset ISO-8859-1, AN15 5 V AN10 1 P AN128 32 P N3 1 P ISO-8859-15 tai UTF-8 54. Tarkistetiedon versio srv_hashversion 55. Tarkiste srv_hash 56. Avaimen sukupolvi srv_keygeneration Merkintä ANxx tarkoittaa, että kenttä sisältää enintään xx aakkosnumeerista merkkiä. P tarkoittaa pakollista tietoa ja V valinnaista. P/V tarkoittaa pakollista tietoa siinä tapauksessa, jos siihen liittyvä valinnainen tieto on annettu. Minimipituus valinnaisten kenttien kohdalla ei tarkoita, että kyseisessä kentässä pitää aina olla sen mittainen merkkijono. Valinnainen kenttä voi olla tyhjä, tai vähintään minimipituuden mittainen. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 3.8.1.1 Kenttien selitteet - palvelun käyttöönoton tiedot Kentän numero Kenttä Selite 1. Palvelun käyttöönoton versio Palvelun käyttöönottosanoman sisällön määrittelyversio. 2. Verkkokauppapalvelun tarjoajan tunnus Suomen Maksuturva Oy:n Verkkokauppaohjelmistotalolle tunnistamista varten antama tunnus. 3. Verkkokauppayrityksen y-tunnus Verkkokauppaa harjoittavan yrityksen Patentti- ja rekisterihallitukselta saama yritystunnus (y-tunnus) 4. Verkkokauppayrityksen nimi Verkkokauppaa harjoittavan yrityksen virallinen nimi 5. Verkkokauppayrityksen markkinointinimi Verkkokauppaa harjoittavan yrityksen markkinointinimi, se nimi, jolla esim. posti toimitetaan. 6. Verkkokauppayrityksen www-osoite 7. Verkkokauppayrityksen sähköpostiosoite Verkkokauppaa harjoittavan yrityksen sähköpostiosoite, yleinen info-osoite. 8. Verkkokauppayrityksen puhelinnumero Verkkokauppaa harjoittavan yrityksen puhelinnumero, pääasiallinen puhelinnumero, esim. vaihde. 9. Verkkokauppayrityksen faksinumero Verkkokauppaa harjoittavan yrityksen faksinumero, pääasiallinen faksinumero. 10. Verkkokaupan oletustilinumero Verkkokaupan tilinumero, jolle Maksuturvan kautta hoidetut maksut hyvitetään kun tilaus on toimitettu perille. Tilinumero tulee olla IBANmuodossa (FI + tarkiste 2 mrk + kotimainen tilinumero 14 mrk) 11. Verkkokaupan nimi Verkkokaupan nimi, se nimi, jota käytetään ostajille. 12. Verkkokaupan www-osoite Verkkokaupan www-osoite, se osoite, jossa Maksuturva-palvelu tulee käyttöön 13. Verkkokaupan asiakaspalvelun yhteystieto Verkkokaupan asiakaspalvelun yhteystieto. Yhteystieto tulostetaan vahvistussähköpostiin Maksuturva-palvelua käyttävälle tilaajalle/ostajalle. Yhteystiedon ei tule sisältää nimeä, mutta sen tulee toimia suomeksi, ruotsiksi ja englanniksi. Esim. ”[email protected], (09) 123 4567”. 14. Verkkokauppayrityksen katuosoite Verkkokauppaa harjoittavan yrityksen pääasiallinen osoite. 15. Verkkokauppayrityksen postilokero Pääasiallisen osoitteen postilokero. 16. Verkkokauppayrityksen postinumero Pääasiallisen osoitteen postinumero 17. Verkkokauppayrityksen postitoimipaikka Pääasiallisen osoitteen postitoimipaikka / kaupunki / kunta 18. Verkkokauppayrityksen maa Pääasiallisen osoitteen maakoodi, standardin ISO 3166-1 mukainen. Oletusarvo FI (Suomi). 19. Verkkokauppayrityksen laskutuskatuosoite Verkkokauppaa harjoittavan yrityksen laskutusosoitteen katuosoite. Laskutusosoite annetaan, mikäli se poikkeaa pääasiallisesta osoitteesta. 20. Verkkokauppayrityksen laskutuspostilokero Laskutusosoitteen postilokero. 21. Verkkokauppayrityksen laskutuspostinumero Laskutusosoitteen postinumero. Pakollinen jos laskutuskatuosoite annetaan. 22. Verkkokauppayrityksen laskutuspostitoimipaikka Laskutusosoitteen postitoimipaikka / kaupunki / kunta. Pakollinen jos laskutuskatuosoite annetaan. 23. Verkkokauppayrityksen laskutusmaa Laskutusosoitteen maakoodi, standardin ISO 3166-1 mukainen. Oletusarvo FI (Suomi). 24. Verkkokaupan katuosoite Verkkokaupan osoitteen katuosoite. Verkkokaupan osoite annetaan, mikäli se poikkeaa pääasiallisesta osoitteesta. 25. Verkkokaupan postilokero Verkkokaupan postilokero. 26. Verkkokaupan postinumero Verkkokaupan postinumero. Pakollinen jos verkkokaupan katuosoite annetaan. Verkkokauppaa harjoittavan yrityksen kotisivut. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 89 / 129 90 / 129 Maksuturvan maksupalvelun integrointiohjeet 27. Verkkokaupan postitoimipaikka Verkkokaupan postitoimipaikka / kaupunki / kunta. Pakollinen jos verkkokaupan katuosoite annetaan. 28. Verkkokaupan maa Verkkokaupan maakoodi, standardin ISO 3166-1 mukainen. Oletusarvo FI (Suomi). 29. Verkkokauppayrityksen yhteyshenkilön nimi Verkkokauppaa harjoittavan yrityksen pääasiallinen yhteyshenkilö Suomen Maksuturvalle. 30. Verkkokauppayrityksen yhteyshenkilön sähköpostiosoite Yhteyshenkilön sähköpostiosoite 31. Verkkokauppayrityksen yhteyshenkilön puhelinnumero Yhteyshenkilön puhelinnumero 32. Verkkokauppayrityksen yhteyshenkilön matkapuhelinnumero Yhteyshenkilön matkapuhelinnumero 33. Verkkokauppayrityksen yhteyshenkilön faksinumero Yhteyshenkilön faksinumero 34. Verkkokauppayrityksen laskutusyhteyshenkilön nimi Verkkokauppaa harjoittavan yrityksen laskutusyhteyshenkilö Suomen Maksuturvalle. 35. Verkkokauppayrityksen Laskutusyhteyshenkilön sähköpostiosoite. Pakollinen jos laskutusyhteyshenkilö laskutusyhteyshenkilön sähköpostiosoite annetaan. 36. Verkkokauppayrityksen laskutusyhteyshenkilön puhelinnumero Laskutusyhteyshenkilön puhelinnumero. Pakollinen jos laskutusyhteyshenkilö annetaan. 37. Verkkokauppayrityksen laskutusyhteyshenkilön matkapuhelinnumero Laskutusyhteyshenkilön matkapuhelinnumero 38. Verkkokauppayrityksen laskutusyhteyshenkilön faksinumero Laskutusyhteyshenkilön faksinumero 39. Verkkokaupaan teknisen yhteyshenkilön nimi Verkkokaupan tekninen yhteyshenkilö Suomen Maksuturvalle. 40. Verkkokaupan teknisen yhteyshenkilön sähköpostiosoite Teknisen yhteyshenkilön sähköpostiosoite. Pakollinen jos tekninen yhteyshenkilö annetaan. 41. Verkkokaupan teknisen yhteyshenkilön puhelinnumero Teknisen yhteyshenkilön puhelinnumero. Pakollinen jos tekninen yhteyshenkilö annetaan. 42. Verkkokaupan teknisen yhteyshenkilön matkapuhelinnumero Teknisen yhteyshenkilön matkapuhelinnumero 43. Verkkokaupan teknisen yhteyshenkilön faksinumero Teknisen yhteyshenkilön faksinumero 44. Verkkokaupan Maksuturva-maksutavat Verkkokaupan käyttämien toimitustapojen tunnisteet. Tunnisteet löytyvät osoitteesta https://www.maksuturva.fi/palvelut/kauppiaille/kauppiasmateriaali.html Kentän ensimmäinen merkki määrittelee käytetyn erotusmerkin, joka ei saa esiintyä osana maksutapoja. Suosituksena puolipiste. Ensimmäisenä merkkinä tulee olla erotinmerkki, vaikka kenttä sisältäisi vain yhden maksutavan. Jos maksutapatietoa ei anneta, perustetaan Maksuturva-palvelun kaikilla sillä hetkellä tarjottavilla maksutavoilla. 45. Verkkokaupan Maksuturva-toimitustavat Verkkokaupan käyttämien toimitustapojen tunnisteet. Tunnisteet löytyvät osoitteesta https://www.maksuturva.fi/palvelut/kauppiaille/kauppiasmateriaali.html Kentän ensimmäinen merkki määrittelee käytetyn erotusmerkin, joka ei saa esiintyä osana toimitustapoja. Suosituksena puolipiste. Ensimmäisenä Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet merkkinä tulee olla erotinmerkki, vaikka kenttä sisältäisi vain yhden toimitustavan. 46. Verkkokaupan Maksuturva-palvelun voimaantulopäivä Päivämäärä, josta alkaen Maksuturvaa halutaan käyttää verkkokaupassa. Jos jätetään antamatta, palvelu astuu voimaan heti kun sopimus on allekirjoitettu ja käsitelty Suomen Maksuturvassa. 47. Kampanjakoodi Ei käytössä. Suomen Maksuturvan kanssa sovittava palvelun ehtoihin ja/tai hintaan vaikuttava kampanjakoodi. 48. Lisätietoa tilauksesta Vapaamuotoista tietoa tilauksesta. 49. Vastauksen tyyppi Määrittää missä muodossa vastaussanoma tehdään. Vaihtoehdot ovat POST ja XML – MerchantSubscription –osoitetta käytettäessä POST, NewService – osoitetta käytettäessa XML. 50. Ok –paluuosoite Osoite, johon vastaussanoma ohjataan onnistuneen palvelun perustamisen jälkeen. Osoitteen tulee sisältää myös protokolla (http/https). 51. Virhe –paluuosoite Osoite, johon vastaussanoma ohjataan, jos perustamisessa tapahtuu virhe. Osoitteen tulee sisältää myös protokolla (http/https). 52. Peruutus-paluuosoite Osoite, johon vastaussanoma ohjataan, jos perustaminen keskeytetään käyttäjän toimesta. Osoitteen tulee sisältää myös protokolla (http/https). 53. Tarkisteen laskentamerkistö Kertoo, missä merkistössä tarkisteen laskentaan käytetty merkkijono oli tarkistetta laskettaessa. Sallitut arvot ovat ISO-8859-1, ISO-8859-15 ja UTF-8, oletus on ISO-8859-1. 54. Tarkistetiedon versio Tarkisteen laskennassa käytetty laskentaversio (algoritmin nimi, katso tarkempi kuvaus Rajapintojen Integrointiohjeesta) 55. Tarkiste Sanoman kentistä ja verkkokaupan salaisesta avaimesta laskettu tarkiste. Tarkiste lasketaan seuraavista kentistä: • srv_webstorewww 56. Avaimen sukupolvi Verkkokaupan salaisen avaimen sukupolvinumero. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 91 / 129 92 / 129 Maksuturvan maksupalvelun integrointiohjeet 3.8.2 Palvelun käyttöönoton vastaussanoman tiedot Kun palvelu perustettiin onnistuneesti, seuraavanlainen tietosisältö välitetään onnistuneen palvelun käyttöönoton jälkeen ok-osoitteeseen (srv_okreturn). Kentän Kenttä numero 1. Palvelun käyttöönoton Tiedon nimi Arvo input name= value= Muoto P/V 0002 AN4 P AN15 P AN200 P AN50 P AN1056 P srv_extranetuserid AN50 P srv_extranetcredential AN1056 P srv_state AN5 P srv_version versio 2. Verkkokauppayrityksen srv_businessid y-tunnus 3. Verkkokaupan www- srv_webstorewww osoite 4. Verkkokaupan tekninen srv_interfaceuserid tunnus 5. Verkkokaupan salainen srv_interfacecredential avain 6. KauppiasExtranettunnus 7. KauppiasExtranetsalasana 8. Palvelun käyttöönoton tila 9. Tarkiste srv_hash AN128 P Kun palvelua ei perustettu, seuraavanlainen tietosisältö välitetään epäonnistuneen tai verkkokaupan keskeyttämän palvelun käyttöönoton jälkeen virhe-osoitteeseen (srv_erroreturn) tai keskeytysosoitteeseen (srv_cancelreturn). Kentän Kenttä numero 1. Palvelun käyttöönoton Tiedon nimi Arvo input name= value= Muoto P/V 0002 AN4 P AN15 P srv_webstorewww AN200 P srv_errorcode AN5 P srv_errordescription AN1000 P srv_version versio 2. Verkkokauppayrityksen srv_businessid y-tunnus 3. Verkkokaupan wwwosoite 10. Palvelun käyttöönoton virhekoodi 11. Palvelun käyttöönoton virheen selite Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 93 / 129 3.8.2.1 Kenttien selitteet - Palvelun käyttöönoton vastaussanoman tiedot Kentän Kenttä Selite numero 1. Palvelun käyttöönoton Palvelun käyttöönottosanoman sisällön määrittelyversio. versio 2. Verkkokauppayrityksen y- Verkkokauppaa harjoittavan yrityksen Patentti- ja rekisterihallitukselta saama yritystunnus tunnus (y-tunnus) 3. Verkkokaupan www-osoite Verkkokaupan www-osoite, se osoite, jossa Maksuturva-palvelu tulee käyttöön 4. Verkkokaupan tekninen Suomen Maksuturva Oy:n Kauppiaalle tunnistamista varten antama tunnus rajapintojen tunnus käyttöön. Verkkokaupan salainen Tekniseen tunnukseen liittyvä salainen avain tarkisteiden laskentaa varten. 5. avain 6. KauppiasExtranet-tunnus Suomen Maksuturva Oy:n Kauppiaalle tunnistamista varten antama tunnus KauppiasExtranetin käyttöön. 7. KauppiasExtranet- KauppiasExtranetin käyttöön liittyvä salasana. salasana 8. Palvelun käyttöönoton tila Asiakkaan ja palvelun perustamiseen liittyvä tilatieto. 10 = asiakas ja palvelu on perustettu 20 = palvelu on perustettu 30 = aiemmin perustettu palvelu allekirjoitettiin 10. Tarkiste Sanoman kentistä ja verkkokaupan salaisesta avaimesta laskettu tarkiste. Tarkisteen laskennassa käytetään samoja versio-, avain- ym. tietoja kuin sisään tulevalla sanomalla. Tarkiste lasketaan näistä kentistä: • srv_businessid • srv_webstorewww • srv_interfaceuserid • srv_interfacecredential • srv_extranetuserid • srv_extranetcredential • srv_state Kursivoidut tulivat tarkisteeseen uusina rajapinnan versiossa 1.1 (sanoma 0002). 11. Palvelun käyttöönoton virhekoodi Virheeseen liittyvä tarkennus: • 10 = Virheitä rajapinnassa välitetyissä tiedoissa • 20 = Verkkokaupalle on jo perustettu palvelu • 30 = Tekninen virhe • 40 = Kauppias keskeytti palvelun käyttöönoton 12. Palvelun käyttöönoton Virheestä riippuvainen selite, joka edelleen selventää mistä virhe johtui (esim. luettelo virheen selite puuttuvista tai virheellisistä tiedoista). Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 94 / 129 Maksuturvan maksupalvelun integrointiohjeet 3.9 Tarkisteen laskenta Jokainen sanoma sisältää tarkisteen (hash), joka on laskettu rajapintakuvauksessa nimetyistä tiedoista (yleensä sanoman pakollisista tiedoista). Tarkisteen laskennassa voi käyttää seuraavia algoritmeja: Algoritmin nimi Algoritmi SHA-512 512 -bittinen SHA-2 SHA-256 256 -bittinen SHA-2 SHA-1 160 -bittinen SHA-1 MD5 MD5 Tarkiste lasketaan siis kunkin sanoman rajapintakuvauksessa määritellyistä kentistä. Tarkisteen laskennassa välitettävät tiedot laitetaan luetellussa järjestyksessä peräkkäin ja jokaisen tiedon perään laitetaan & -merkki. Lueteltujen tietojen perään laitetaan Suomen Maksuturva Oy:n toimittama salainen avain ja tämän perään vielä & -merkki. Näin syntyneestä merkkijonosta muodostetaan tarkiste käyttäen yhtä sallituista algoritmeista. Tarkistetiedon versio -kenttään laitetaan tämän algoritmin nimi siinä muodossa kuin se näkyy sallittujen algoritmien listauksessa. Mikäli tieto on valinnainen ja mukana tarkisteessa, mutta sitä ei välitetä tai se on tyhjä, tarkisteen laskennassa EI tällöin laiteta myöskään & merkkiä sen tiedon kohdalle. Tarkiste voidaan välittää isoilla tai pienillä kirjaimilla, mutta vastauksissa tarkiste on aina isoilla kirjaimilla. Esimerkki: Oletetaan, että tarkiste lasketaan seuraavista kentistä (suluissa esimerkissä käytettävä arvo): • kentta1 (123) • kentta2 (ABC) • kentta3 (K) Salaisena avaimena käytössä on ”testiavain” ilman lainausmerkkejä. Tarkiste lasketaan tällöin seuraavasta merkkijonosta: 123&ABC&K&testiavain& Oletuksena tarkiste on laskettava ISO-8859-1 muotoisesta merkkijonosta, mutta muutkin merkistöt ovat sallittuja. Maksurajapinnalle tarkisteenlaskennassa käytetty merkistö voidaan välittää pmt_charset parametrina. Sen arvoina sallitaan ainakin ISO-8859-1, ISO-8859-15 ja UTF-8. Lisäksi riippumatta tarkisteen laskennan merkistöstä, pitää maksurajapinnan versiosta 0004 alkaen välittää parametri pmt_charsethttp, joka kertoo verkkokaupan käyttämän merkistön. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 95 / 129 3.9.1 Vinkkejä tarkisteen laskennan avuksi Kopioi salainen avain ja verkkokauppatunnus uudelleen vaikka Notepadin kautta. Niihin tulee usein näkymättömiä space- tai rivinvaihtomerkkejä Outlookista tai Wordista. Kokeile toimiiko hash oikein jos tilauksessa ei ole mitään erikoismerkkejä, ääkkösiä tai ylipäätään USASCII merkistön ulkopuolisia merkkejä. Jos toimii, niin vika on merkistöjen enkoodauksissa tai niiden ilmoittamisessa Maksuturvan maksurajapinnalle: • Tietojen välityksen merkistö / pmt_charsethttp: Verkkokaupan selaimen suuntaan käyttämä enkoodaus. Selaimen pitää oikeasti välittää tiedot tässä enkoodauksessa. Selaimen tiedoista (view page info yms.) näkyy missä muodossa se välittää tiedot. Ne ovat siinä muodossa kuin se verkkokaupan sivu mikä viimeisenä näkyy ennen Maksamiseen siirtymistä. • Hash-laskennan merkistö / pmt_charset: Hash-laskenta (MD5 ja kaikki muutkin) ovat binäärioperaatioita. Merkkijono muunnetaan binääriksi ennen laskentaa. Siten esim "Ä" UTF-8-merkistössä saa eri hash-arvon kuin "Ä" Latin-1-merkistössä. Koodaajan on tiedettävä tai määriteltävä hash-funktiolle, mitä merkistöä se käyttää muuntaessaan merkkijonon binääriksi ennen hashin laskemista, ja tämä sama merkistö on välitettävä Maksuturvalle parametrissa pmt_charset Tarkista ettei hashattavassa merkkijonossa missään välissä ole kahta & merkkiä (ampersand) peräkkäin, sillä sellainen tulee vain hashiin mukaan tulevien tietojen perään, tyhjiä kenttiä ei laiteta hashiin eikä niiden perässä olevia & merkkejä myöskään. Merkkijonon viimeinen merkki on myös &. Katso läpi tarkisteenlaskennan parametrilista rajapintakuvauksesta. Rajapintakutsujen ja vastaussanomien tarkisteiden parametrit eroavat toisistaan erinäisten valinnaisuuksien yms. vuoksi. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 96 / 129 Maksuturvan maksupalvelun integrointiohjeet 4. Palvelun testaaminen Palvelun testaaminen on täysin ilmaista ja tapauksesta riippuen siihen käytetään yleisiä ja/tai yksilöllisiä testitunnuksia. Palvelua testattaessa ei milloinkaan käsitellä oikeaa rahaa tai seurata toimituksia. • Yleiset testitunnukset (ns. sandbox-testaus) on tarkoitettu verkkokaupan ja Maksuturvan välisen tietoliikenneyhteyden ja välitetyn tietosisällön oikeellisuuden tarkistamiseen. Etenkin tarkisteen laskenta kannattaa todeta toimivaksi yleisillä testitunnuksilla, joka auttaa asiassa antamalla diagnostiikkaa verkkokaupan integraation toteuttajalle. • Yksilöllisillä testitunnuksilla testataan ostajan maksuprosessia sekä verkkokaupan tilausten seurantaa ja hallintaa. Maksaminen tapahtuu esimerkiksi verkkopankkien testipalveluissa ja verkkokaupalla on mahdollisuus hallita tilauksia KauppiasExtranet-palvelussa. Myös Verkko-ostajan palvelut ovat saatavilla. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 97 / 129 4.1 Sandbox-testaus Yleisen testitunnuksen eli "sandbox-testauksen" avulla on helpointa todentaa muun muassa tarkisteenlaskennan toimivuus. Yleisen testitunnuksen tiedot Tekninen tunnus ”testikauppias” Salainen avain ”11223344556677889900” Salaisen avaimen sukupolvi "1" Yleisiä testitunnuksia käytettäessä palvelu toimii erillisessä testitilassa, jolloin verkkokaupan välittämät tiedot eivät tallennu minnekään ja esimerkiksi tilausta maksettaessa siirrytään erilliselle testi-/ diagnostiikkasivulle. Palvelumme todentaa verkkokaupan välittämän tietosisällön ja joko ilmoittaa virheistä tai muodostaa testattavan rajapinnan mukaisen vastaussivun tai joissakin tapauksissa XML dokumentin. Testitunnusta käytettäessä sanomat voidaan lähettää tuotannon (https://www.maksuturva.fi) tai testiympäristön (http://test1.maksuturva.fi) palveluosoitteisiin. Toki suositellumpaa on käyttää testiympäristöä testaamiseen. Esimerkki Esimerkki yleisten testitunnusten tulossivusta Maksaminen -rajapintaa kutsuttaessa: Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 98 / 129 Maksuturvan maksupalvelun integrointiohjeet Mikäli välitetyssä viestissä on virheitä, asia ilmoitetaan sivun yläreunassa: Esimerkki virheestä viestin tarkisteessa: Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 99 / 129 4.1.1 Vinkkejä virheiden paikallistamiseen "Hash value is invalid" vastaus testisivulla Tarkiste (hash) muodostetaan yhdistämällä rajapintakutsun muuttujien arvoista sekä palvelun yksilöllisestä salaisesta avaimesta merkkijono (string), jonka jokainen osa erotetaan toisistaan &merkillä. Yhdenkin merkin puuttuminen tai virhe tuottaa erilaisen tarkisteen. Salaista avainta ei koskaan välitetä rajapintakutsussa. Sen merkitys on olla tuon merkkijonon salainen osa, joka on ainoastaan verkkokaupan ja Maksuturvan tiedossa. Vaikka ulkopuolinen taho tuntisi viestin kaikki muut tietueet (tilausnumerot, asiakkaan tiedot, tuotteet jne.), ei tämä kykene tuntematta verkkokaupan salaista avainta muodostamaan rajapintakutsun viestisisällöstä samaa tarkistesummaa kuin verkkokauppaosapuoli ja Maksuturva. Tämä kuitenkin merkitsee, että verkkokauppaohjelma tai verkkokauppaan integroitu Maksuturvamoduuli voi synnyttää virheellisen tarkisteen esimerkiksi, jos: • tarkisteen laskentaan käytetystä merkkijonosta puuttuu jokin (kussakin rajapintakuvauksessa määritellyistä) tietueista, joukossa on ylimääräinen tietue tai merkkijono on muodostettu tietueista väärässä järjestyksessä. • verkkokaupan tunnukset tai salainen avain ovat väärät. Tarkista, ettei tunnuksen tai salaisen avaimen alkuun tai loppuun jäänyt ylimääräisiä merkkejä tai välilyöntejä merkkejä. • johonkin merkkijonon tietueista alkuun tai loppuun on tullut - mahdollisesti näkymättömiä ylimääräisiä merkkejä tai välilyöntejä • rajapintakutsun viestissä on ASCII-merkistön ulkopuolisia merkkejä ja kutsun pmt_charset-muuttujan arvona on eri merkistö kuin mitä verkkokauppa on todellisuudessa käyttänyt tarkisteen laskentaan (esimerkiksi pmt_charset=UTF-8, mutta palvelin käyttää ISO-8859-15-merkistöä). Näitä merkkejä ovat esimerkiksi å, ä, ö tai – (eli pitkä ajatusviiva eli ns. emdash). Esimerkiksi merkki 'ä' on UTF-8-merkistössä heksadesimaalimuodossa 'c3a4', mutta ISO-8859-15-merkistössä 'E4'. Myös esimerkiksi tekstinkäsittelyohjelmista (esimerkiksi Microsoft Wordista) tuotetietoja verkkokauppaan kopioitaessa saattaa mukaan kopioitua erikoismerkkejä, jotka verkkokauppa tallentaa tuotetietoihin, muttei osaa niitä käyttäjälle näyttää. Tällöin on mahdollista, että muodostaessaan rajapintakutsun viestiä verkkokauppasovellus huomioi näkymättömät erikoismerkit laskiessaan tarkistetta, mutta erikoismerkit suodattuvat pois Maksuturvalle välittyvistä viestin tietueista. Verkkokauppa ja Maksuturva siis laskevat tällöin tarkistetta aineistoista, joissa on yhden tai useamman merkin ero. Keskeinen ratkaisu on varmistaa, että tarkisteen laskentaan käytetään täsmälleen samoja tietuearvoja kuin viestisanomassa välitettäviin muuttujiinkin. Muuttujien arvot tulisikin suodattaa muista kuin ennalta hyväksytyistä erikoismerkeistä ennen kuin niitä sijoitetaan osaksi viestiä tai tarkisteenlaskennan merkkijonoa. Mikäli merkkierot eivät muuten paljastu, kannattaa verkkokauppaohjelmiston tai sen Maksuturvan integraatiosta vastaavaan osaan lisätä ainoastaan testaamisen ajaksi tarkisteenlaskentaan käytettävän merkkijonon lokitus. Lokitettua merkkijonoa voi tällöin verrata sandbox-testisivun Maksuturvan käyttämään merkkijonoon. Lokitetun merkkijonon ja Maksuturvan merkkijonon tulee olla täysin yhtenevät, joten tietojen toisistaan poikkeava järjestys ja ylimääräiset merkit ja välilyönnit voi näin huomata. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 100 / 129 Maksuturvan maksupalvelun integrointiohjeet 4.1.2 Rajapintakutsujen testauksen kuvaus yleisillä testitunnuksilla Maksamisen testaus Tarkistetaan, että kenttien sisällöt vastaavat rajapintakuvausta ja että esim. viite on oikein muodostettu. Vastaussivulla on linkit joiden avulla voi simuloida ok-, peruutus-, virhe- ja viivästetty maksu -paluuta verkkokauppaan. Tapahtuman tilan kyselyn testaus Testatessa testitunnuksella voi maksun tunnistetiedot olla mitä tahansa, koska tapahtuman tila generoidaan arvalla vastaukseen. Tila on joku rajapintakuvauksessa kuvattu ja ilmaisee missä tilassa tapahtuma on juuri nyt (esim. maksamatta, maksettu, toimituksessa, hyvitetty). Toimitustietojen hallinnan testaus (vain Tyyväisyystakuu-palvelut) Tarkistetaan, että kenttien sisällöt vastaavat rajapintakuvausta ja että esim lähetystunnisteissa ei ole muotovirheitä. Ei osaa validoida seurantakoodeja täydellisesti, mutta suorituu hommasta melko hyvin etenkin suurien suomalaisten logistiikkayritysten lähetystunnisteiden tapauksessa. Voimassa olevat toimitustapojen tunnisteet on listattu osiossa Toimitustapojen tunnisteet. Maksutapahtuman muuttaminen (vain Tyyväisyystakuu-palvelut) Testatessa testitunnuksella voi maksun tunnistetiedot olla mitä tahansa, koska tapahtuman peruutuksen onnistuminen generoidaan arvalla vastaukseen. Vastauskoodi on joku rajapintakuvauksessa kuvattu ja ilmaisee onnistuiko peruutus vai ei. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 101 / 129 4.2 Yksilölliset testitunnukset Yksilöllisillä tunnuksilla testaaminen Käytettäessä testiympäristön yksilöllisiä tunnuksia voidaan mm. simuloida ostajan maksuprosessia sekä Tyytyväisyystakuun muutostyökaluja ostajan ja verkkokaupan näkökulmasta. Testiympäristössä ei milloinkaan käytetä aitoa rahaa, vaan kaikki verkkopankki- ja laskutuksella maksamiset ohjataan kyseisten rahoituslaitosten testiympäristöihin. Käytettäessä testiympäristön testitunnuksia, palvelukutsut ohjataan testiympäristön osoitteeseen http://test1.maksuturva.fi eli esimerkiksi maksamisen tapauksessa http://test1.maksuturva.fi/ NewPaymentExtended.pmt ja maksutapahtuman tilan kyselyn tapauksessa http://test1.maksuturva.fi/ PaymentStatusQuery.pmt. Yksilöllisten tunnusten tilaaminen Verkkokauppa voi tilata tunnukset itsepalveluna tilauspalvelusta: Testiympäristö: Maksuturva Basic, Maksuturva Gold, eMaksut ja eMaksut Laaja: http://test1.maksuturva.fi/tilaapalvelu Posti Maksuturva Basic, Posti Maksuturva Gold: http://test1.maksuturva.fi/tilaaPostiMaksuturva Tuotanto: Maksuturva Basic, Maksuturva Gold, eMaksut ja eMaksut Laaja: https://www.maksuturva.fi/tilaapalvelu Posti Maksuturva Basic, Posti Maksuturva Gold: https://www.maksuturva.fi/tilaaPostiMaksuturva Tuotanto- vs. testiympäristö Huomaathan, että tuotanto ja testiympäristö ovat täysin toisistaan riippumattomia eivätkä testitunnukset toimi tuotannossa; tai toisin päin. Käytettäessä tuotantopalveluita, oikeita maksutapahtumia ja aitoa rahaa, palvelukutsut ohjataan Maksuturvan SSL-suojattuun tuotantoympäristöön https://www.maksuturva.fi eli esimerkiksi maksamisen tapauksessa https://www.maksuturva.fi/NewPaymentExtended.pmt ja maksutapahtuman tilan kyselyn tapauksessa https://www.maksuturva.fi/PaymentStatusQuery.pmt. Huomaathan, että testiympäristön yhteys ei käytä tuotantopalvelun tapaan SSL-suojausta (HTTP vs HTTPS). Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 102 / 129 Maksuturvan maksupalvelun integrointiohjeet 4.2.1 Verkkopankkien testitunnukset Aktia Käyttäjätunnus: 12345678 Salasana: 123456 Turvaluku: 1234 Turvaluku 2: 1234 Danske Bank Testattaessa tulee käyttää omia asiakastunnuksia. Tehtyjä maksuja ei veloiteta tililtä. Handelsbanken Käyttäjätunnus: 11111111 Salasana: 123456 Turvaluku: 123456 Turvaluku 2: 123456 LähiTapiola Käyttäjätunnus: 12345678 Salasana: mitä tahansa numeroita Tunnusluku: neljä mitä tahansa numeroa Tunnusluku 2: neljä mitä tahansa numeroa Nordea Tunnus: 123456 Salasana: 1234 Vahvistustunnus: neljä mitä tahansa numeroa Osuuspankki Käyttäjätunnus: 123456 Salasana: 7890 Avainluku: neljä mitä tahansa numeroa POP Pankki Käyttäjätunnus: 11111111 Salasana: 123456 Turvaluku: 123456 Turvaluku 2: 123456 S-Pankki Käyttäjätunnus: 12345678 Salasana: mitä tahansa numeroita Tunnusluku: neljä mitä tahansa numeroa Tunnusluku 2: neljä mitä tahansa numeroa Säästöpankki Käyttäjätunnus: 11111111 Salasana: 123456 Turvaluku: 123456 Turvaluku 2: 123456 Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet Ålandsbanken Käyttäjätunnus: 12345678 Salasana: mitä tahansa numeroita Tunnusluku: neljä mitä tahansa numeroa Tunnusluku 2: neljä mitä tahansa numeroa Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 103 / 129 104 / 129 Maksuturvan maksupalvelun integrointiohjeet 4.2.2 Luotonmyöntäjien testitunnukset Maksuturva Lasku ja Maksuturva Erämaksu (Maksajana YKSITYISHENKILÖ) Henkilötunnus Toiminta testiympäristössä 250549-9980 Maksaminen onnistuu 160264-999N Maksaminen ei onnistu (luottotiedot liian heikot) 300890-9290 Maksaminen onnistuu, mutta edellyttää Laskun tapauksessa TUPAS-tunnistautumista, tai esim. koska väestörekisterin osoite ei vastaa tilauksen laskutus- ja toimitusosoitetta. Lisäksi testaajan Maksuturvan on pitänyt erikseen aktivoida palvelulla "Optionaalinen TUPAS", mikä oma hetu mahdollistaa Maksturva Laskulla tilaamisen ilman verkkopankkitunnuksia tilattaessa väestörekisteriosoitteeseen. Maksuturva Laskun ja Maksuturva Erämaksun tapauksessa Luotonmyöntäjän testijärjestelmä ei aidosti vertaa tilauksen osoitetietoja väestörekisteritietoihin vaan niiden oletetaan aina täsmäävän keskenään. Poikkeuksen tähän tekee yllä olevassa taulukossa esitelty henkilötunnus 300890-9290, minkä avulla tilannetta on mahdollista simuloida. SveaWebPay Lasku ja SveaWebPay Osamaksu (Maksajana YKSITYISHENKILÖ) Henkilötunnus Laskutusosoite Toiminta testiympäristössä 160264-999N Atomitie 2 C Maksaminen onnistuu 00370 Helsinki 111248-999C mitä tahansa Maksaminen ei onnistu 261295-9985 170172-998J "SveaWebPay-palvelusta saadun vastauksen perusteella Laskulla tai esim. maksamista ei valitettavasti voida hyväksyä. testaajan oma hetu Voit halutessasi valita toisen maksutavan." SveaWebPay Laskun ja SveaWebPay Osamaksun tapauksessa testijärjestelmä vertaa tilauksen osoitetietoja Luotonmyöntäjän palauttamiin väestörekisteritietoihin. Mikäli ne eivät täsmää keskenään, järjestelmä näyttää maksajalle asiasta selkeän virheilmoituksen ja osoite on mahdollista vaihtaa tilauksen tietoihin verkkokaupassa. SveaWebPay Lasku (Maksajana YRITYS) Y-tunnus Laskutusosoite Toiminta testiympäristössä 9999999-2 Testitie 1 Maksaminen onnistuu 00370 Helsinki 8888888-3 Testitie 1 Maksaminen ei onnistu 7777777-4 00370 Helsinki 6666666-5 Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 5. Esimerkkejä 105 Tässä osiossa näet joitakin esimerkkejä palvelurajapintojen pyynnöistä ja vastauksista. ŋ Huomaathan, että esimerkit eivät ole toimivia vaan niiden tarkoitus on antaa integroijalle nopeasti näkemys siitä, miltä pyyntö- tai vastaussanomat näyttävät. Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] / 129 106 / 129 Maksuturvan maksupalvelun integrointiohjeet 5.1 Maksutapojen hakeminen (ostoskorikohtaisesti) Esimerkki pyynnöstä (HTTP GET): http://test1.maksuturva.fi/GetPaymentMethods.pmt? sellerid=SELLERID&request_locale=fi&totalamount=174,90 https://www.maksuturva.fi/GetPaymentMethods.pmt? sellerid=SELLERID&request_locale=fi&totalamount=174,90 Esimerkki vastauksesta (HTTP RESPONSE): <?xml version="1.0" encoding="ISO-8859-1" standalone="no"?> <paymentmethods> <paymentmethod> <code>FI01</code> <displayname>Nordea E-maksu</displayname> </paymentmethod> <paymentmethod> <code>FI02</code> <displayname>Danske Bank Verkkomaksu</displayname> </paymentmethod> <paymentmethod> <code>FI03</code> <displayname>Aktia verkkomaksu</displayname> </paymentmethod> <paymentmethod> <code>FI04</code> <displayname>POP Pankin verkkomaksu</displayname> </paymentmethod> <paymentmethod> <code>FI05</code> <displayname>Tapiola Pankki Verkkomaksu</displayname> </paymentmethod> <paymentmethod> <code>FI06</code> <displayname>Osuuspankki Verkkomaksu</displayname> </paymentmethod> <paymentmethod> <code>FI07</code> <displayname>Ålandsbanken E-maksu</displayname> </paymentmethod> <paymentmethod> <code>FI08</code> <displayname>Säästöpankin verkkomaksu</displayname> </paymentmethod> <paymentmethod> <code>FI09</code> <displayname>Handelsbanken Verkkomaksu</displayname> </paymentmethod> <paymentmethod> <code>FI10</code> Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet <displayname>S-pankki Verkkomaksu</displayname> </paymentmethod> <paymentmethod> <code>FI50</code> <displayname>Korttimaksu (Visa, Visa Electron, MasterCard)</displayname> </paymentmethod> <paymentmethod> <code>FI60</code> <displayname>Maksuturva Lasku</displayname> </paymentmethod> <paymentmethod> <code>FI61</code> <displayname>Maksuturva Erämaksu</displayname> </paymentmethod> <paymentmethod> <code>FI70</code> <displayname>SveaWebPay Lasku</displayname> </paymentmethod> <paymentmethod> <code>FI71</code> <displayname>SveaWebPay Osamaksu</displayname> </paymentmethod> <paymentmethod> <code>FI72</code> <displayname>Yrityslasku</displayname> </paymentmethod> <paymentmethod> <code>USPP</code> <displayname>PayPal</displayname> </paymentmethod> <paymentmethod> <code>RBIN</code> <displayname>Resurs Bank Lasku</displayname> </paymentmethod> <paymentmethod> <code>RBPP</code> <displayname>Resurs Bank Osamaksu</displayname> </paymentmethod> </paymentmethods> Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 107 / 129 108 / 129 Maksuturvan maksupalvelun integrointiohjeet 5.2 Dynaamisen kuva-aineiston hakeminen Esimerkkejä löytyy rajapintakuvauksesta: Dynaamisen kuva-aineiston hakeminen Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 109 / 129 5.3 Maksaminen Esimerkkejä pyynnöistä (HTTP POST) Esimerkki 1: • • • • Tyytyväisuustakuu-palvelu (esim. Maksuturva Gold) Laskutus- ja toimitusosoite eroavat toisistaan Kaupan paluuosoitteissa ei ole query string -parametreja Ostaja valitsee maksutavan Maksuturvan maksutavan valinta -lomakkeella <form method="post" action="http://test1.maksuturva.fi/NewPaymentExtended.pmt"> <input type="submit" value="Pay"> <input type="hidden" name="pmt_action" <input type="hidden" name="pmt_version" <input type="hidden" name="pmt_sellerid" <input type="hidden" name="pmt_id" <input type="hidden" name="pmt_orderid" <input type="hidden" name="pmt_reference" <input type="hidden" name="pmt_duedate" <input type="hidden" name="pmt_userlocale" <input type="hidden" name="pmt_amount" <input type="hidden" name="pmt_currency" <input type="hidden" name="pmt_okreturn" return/Success.do" /> <input type="hidden" name="pmt_errorreturn" return/Error.do" /> <input type="hidden" name="pmt_cancelreturn" return/Cancel.do" /> <input type="hidden" name="pmt_delayedpayreturn" return/Cancel.do" /> <input type="hidden" name="pmt_escrow" Tyytyväisyystakuu-palvelu, escrow=Y --> <input type="hidden" name="pmt_escrowchangeallowed" <input type="hidden" name="pmt_buyername" <input type="hidden" name="pmt_buyeraddress" <input type="hidden" name="pmt_buyerpostalcode" <input type="hidden" name="pmt_buyercity" <input type="hidden" name="pmt_buyercountry" <input type="hidden" name="pmt_buyerphone" <input type="hidden" name="pmt_buyeremail" value="[email protected]" /> <input type="hidden" name="pmt_deliveryname" <input type="hidden" name="pmt_deliveryaddress" <input type="hidden" name="pmt_deliverypostalcode" <input type="hidden" name="pmt_deliverycity" <input type="hidden" name="pmt_deliverycountry" <input type="hidden" name="pmt_sellercosts" <input type="hidden" name="pmt_rows" <input type="hidden" name="pmt_row_name1" value="NEW_PAYMENT_EXTENDED" /> value="0004" /> value="ABC123DE" /> value="1998524_1" /> value="1998524" /> value="19985242" /> value="15.10.2014" /> value="fi_FI" /> value="568,10" /> value="EUR" /> value="http://www.mytestshop.fi/pay/ value="http://www.mytestshop.fi/pay/ value="http://www.mytestshop.fi/pay/ value="http://www.mytestshop.fi/pay/ value="Y" /> <!-- value="N" /> value="Teemu Testaaja" /> value="Ruoholahdenkatu 23" /> value="00180" /> value="Helsinki" /> value="FI" /> value="0401234567" /> value="Teemu Testaaja" /> value="Kotikatu 1" /> value="00330" /> value="Helsinki" /> value="FI" /> value="5,00" /> value="4" /> value="Tuote A" /> Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 110 / 129 Maksuturvan maksupalvelun integrointiohjeet <input type="hidden" name="pmt_row_desc1" <input type="hidden" name="pmt_row_quantity1" <input type="hidden" name="pmt_row_deliverydate1" <input type="hidden" name="pmt_row_price_gross1" <!--<input type="hidden" name="pmt_row_price_net1" vaihtoehtoinen brutolle --> <input type="hidden" name="pmt_row_vat1" <input type="hidden" name="pmt_row_discountpercentage1" <input type="hidden" name="pmt_row_type1" <input type="hidden" name="pmt_row_name2" <input type="hidden" name="pmt_row_desc2" kuvaus" /> <input type="hidden" name="pmt_row_quantity2" <input type="hidden" name="pmt_row_deliverydate2" <input type="hidden" name="pmt_row_price_gross2" <!--<input type="hidden" name="pmt_row_price_net2" vaihtoehtoinen brutolle --> <input type="hidden" name="pmt_row_vat2" <input type="hidden" name="pmt_row_discountpercentage2" <input type="hidden" name="pmt_row_type2" <input type="hidden" name="pmt_row_name3" <input type="hidden" name="pmt_row_desc3" <input type="hidden" name="pmt_row_quantity3" <input type="hidden" name="pmt_row_deliverydate3" <input type="hidden" name="pmt_row_price_gross3" <!--<input type="hidden" name="pmt_row_price_net3" vaihtoehtoinen brutolle --> <input type="hidden" name="pmt_row_vat3" <input type="hidden" name="pmt_row_discountpercentage3" <input type="hidden" name="pmt_row_type3" <input type="hidden" name="pmt_row_name4" <input type="hidden" name="pmt_row_desc4" > <input type="hidden" name="pmt_row_quantity4" <input type="hidden" name="pmt_row_deliverydate4" <input type="hidden" name="pmt_row_price_gross4" <!--<input type="hidden" name="pmt_row_price_net4" vaihtoehtoinen brutolle --> <input type="hidden" name="pmt_row_vat4" <input type="hidden" name="pmt_row_discountpercentage4" <input type="hidden" name="pmt_row_type4" <input type="hidden" name="pmt_charset" <input type="hidden" name="pmt_charsethttp" <input type="hidden" name="pmt_hashversion" <input type="hidden" name="pmt_hash" value="D26B59EAD06ED6E44E0B279B61C4894DEEE85A8B" /> <input type="hidden" name="pmt_keygeneration" </form> value="Tuotteen A kuvaus" /> value="2" /> value="15.10.2014" /> value="123,00" /> value="100,00" />--> <!-- netto value="23,00" /> value="0,00" /> value="1" /> value="Räätälöity alennustuote B" /> value="Räätälöidyn alennustuotteen value="1" /> value="15.10.2014" /> value="369,00" /> value="300,00" /> netto value="23,00" /> value="10,00" /> value="4" /> value="Toimituskulut" /> value="Toimitustapa yms." /> value="1" /> value="15.10.2014" /> value="5,00" /> value="5,00" />--> <!-- netto value="0,00" /> value="0,00" /> value="2" /> value="Alennus" /> value="Alennuskupongin koodi tms." / value="1" /> value="15.10.2014" /> value="-10,00" /> value="-10,00" />--> <!-- netto value="0,00" /> value="0,00" /> value="6" /> value="ISO-8859-15" /> value="ISO-8859-15" /> value="SHA-1" /> value="1" /> Esimerkki 2: • Suoramaksupalvelu (esim. eMaksut Laaja) • Laskutus- ja toimitusosoite ovat identtisiä Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 111 / 129 • Kaupan paluuosoitteissa on query string -parametreja • Ostaja on valinnut verkkokaupassa maksutavaksi Maksuturva Laskun (FI60) <form method="post" action="http://test1.maksuturva.fi/NewPaymentExtended.pmt"> <input type="submit" value="Pay"> <input type="hidden" name="pmt_action" <input type="hidden" name="pmt_version" <input type="hidden" name="pmt_sellerid" <input type="hidden" name="pmt_id" <input type="hidden" name="pmt_orderid" <input type="hidden" name="pmt_reference" <input type="hidden" name="pmt_duedate" <input type="hidden" name="pmt_userlocale" <input type="hidden" name="pmt_amount" <input type="hidden" name="pmt_currency" <input type="hidden" name="pmt_okreturn" return/Success.do?paid=1" /> <input type="hidden" name="pmt_errorreturn" return/Error.do?paid=0" /> <input type="hidden" name="pmt_cancelreturn" return/Cancel.do?paid=0" /> <input type="hidden" name="pmt_delayedpayreturn" return/Cancel.do?paid=0" /> <input type="hidden" name="pmt_escrow" Suoramaksupalvelu, escrow=N --> <input type="hidden" name="pmt_escrowchangeallowed" <input type="hidden" name="pmt_paymentmethod" valittu maksutapa --> <input type="hidden" name="pmt_buyername" <input type="hidden" name="pmt_buyeraddress" <input type="hidden" name="pmt_buyerpostalcode" <input type="hidden" name="pmt_buyercity" <input type="hidden" name="pmt_buyercountry" <input type="hidden" name="pmt_buyerphone" <input type="hidden" name="pmt_buyeremail" value="[email protected]" /> <input type="hidden" name="pmt_deliveryname" <input type="hidden" name="pmt_deliveryaddress" <input type="hidden" name="pmt_deliverypostalcode" <input type="hidden" name="pmt_deliverycity" <input type="hidden" name="pmt_deliverycountry" <input type="hidden" name="pmt_sellercosts" <input type="hidden" name="pmt_rows" <input type="hidden" name="pmt_row_name1" <input type="hidden" name="pmt_row_desc1" <input type="hidden" name="pmt_row_quantity1" <input type="hidden" name="pmt_row_deliverydate1" <input type="hidden" name="pmt_row_price_gross1" <!--<input type="hidden" name="pmt_row_price_net1" vaihtoehtoinen brutolle--> <input type="hidden" name="pmt_row_vat1" <input type="hidden" name="pmt_row_discountpercentage1" value="NEW_PAYMENT_EXTENDED" /> value="0004" /> value="ABC123DE" /> value="1998524_1" /> value="1998524" /> value="19985242" /> value="15.10.2014" /> value="fi_FI" /> value="568,10" /> value="EUR" /> value="http://www.mytestshop.fi/pay/ value="http://www.mytestshop.fi/pay/ value="http://www.mytestshop.fi/pay/ value="http://www.mytestshop.fi/pay/ value="N" /> <!-- value="N" /> value="FI60" /> <--- Verkkokaupassa value="Teemu Testaaja" /> value="Ruoholahdenkatu 23" /> value="00180" /> value="Helsinki" /> value="FI" /> value="0401234567" /> value="Teemu Testaaja" /> value="Ruoholahdenkatu 23" /> value="00180" /> value="Helsinki" /> value="FI" /> value="5,00" /> value="4" /> value="Tuote A" /> value="Tuotteen A kuvaus" /> value="2" /> value="15.10.2014" /> value="123,00" /> value="100,00" />--> <!-- netto value="23,00" /> value="0,00" /> Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 112 / 129 Maksuturvan maksupalvelun integrointiohjeet <input type="hidden" name="pmt_row_type1" <input type="hidden" name="pmt_row_name2" <input type="hidden" name="pmt_row_desc2" kuvaus" /> <input type="hidden" name="pmt_row_quantity2" <input type="hidden" name="pmt_row_deliverydate2" <input type="hidden" name="pmt_row_price_gross2" <!--<input type="hidden" name="pmt_row_price_net2" vaihtoehtoinen brutolle --> <input type="hidden" name="pmt_row_vat2" <input type="hidden" name="pmt_row_discountpercentage2" <input type="hidden" name="pmt_row_type2" <input type="hidden" name="pmt_row_name3" <input type="hidden" name="pmt_row_desc3" <input type="hidden" name="pmt_row_quantity3" <input type="hidden" name="pmt_row_deliverydate3" <input type="hidden" name="pmt_row_price_gross3" <!--<input type="hidden" name="pmt_row_price_net3" vaihtoehtoinen brutolle --> <input type="hidden" name="pmt_row_vat3" <input type="hidden" name="pmt_row_discountpercentage3" <input type="hidden" name="pmt_row_type3" <input type="hidden" name="pmt_row_name4" <input type="hidden" name="pmt_row_desc4" > <input type="hidden" name="pmt_row_quantity4" <input type="hidden" name="pmt_row_deliverydate4" <input type="hidden" name="pmt_row_price_gross4" <!--<input type="hidden" name="pmt_row_price_net4" vaihtoehtoinen brutolle --> <input type="hidden" name="pmt_row_vat4" <input type="hidden" name="pmt_row_discountpercentage4" <input type="hidden" name="pmt_row_type4" <input type="hidden" name="pmt_charset" <input type="hidden" name="pmt_charsethttp" <input type="hidden" name="pmt_hashversion" <input type="hidden" name="pmt_hash" value="D26B59EAD06ED6E44E0B279B61C4894DEEE85A8B" /> <input type="hidden" name="pmt_keygeneration" </form> value="1" /> value="Räätälöity alennustuote B" /> value="Räätälöidyn alennustuotteen value="1" /> value="15.10.2014" /> value="369,00" /> value="300,00" />--> <!-- netto value="23,00" /> value="10,00" /> value="4" /> value="Toimituskulut" /> value="Toimitustapa yms." /> value="1" /> value="15.10.2014" /> value="5,00" /> value="5,00" />--> <!-- netto value="0,00" /> value="0,00" /> value="2" /> value="Alennus" /> value="Alennuskupongin koodi tms." / value="1" /> value="15.10.2014" /> value="-10,00" /> value="-10,00" />--> <!-- netto value="0,00" /> value="0,00" /> value="6" /> value="ISO-8859-15" /> value="ISO-8859-15" /> value="SHA-1" /> value="1" /> Esimerkkejä OK-vastauksista (HTTP 302) Huomaathan, että kukin vastausesimerkki on yksi URL, joka on jaettu usealle riville query string parametreittain. http://www.mytestshop.fi/pay/return/Success.do ?pmt_action=NEW_PAYMENT_EXTENDED &pmt_version=0004 &pmt_id=1998524_1 &pmt_reference=00000000000019985242 &pmt_amount=568,10 &pmt_currency=EUR Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 113 / 129 &pmt_sellercosts=5,00 &pmt_escrow=Y &pmt_hash=F7C0E8A3F5F5FEDDC2B945F0246DE5FD27B9206B &pmt_paymentmethod=FI01 http://www.mytestshop.fi/pay/return/Success.do?paid=1 &pmt_action=NEW_PAYMENT_EXTENDED &pmt_version=0004 &pmt_id=1998524_1 &pmt_reference=00000000000019985242 &pmt_amount=568,10 &pmt_currency=EUR &pmt_sellercosts=5,00 &pmt_escrow=Y &pmt_hash=FFDFB9E0287706794232C4E34AF1FA11F7560288 &pmt_paymentmethod=FI60 Esimerkkejä CANCEL-vastauksista (HTTP 302) http://www.mytestshop.fi/pay/return/Cancel.do?pmt_id=1998524_1 http://www.mytestshop.fi/pay/return/Cancel.do?paid=0&pmt_id=1998524_1 Esimerkkejä ERROR-vastauksista (HTTP 302) http://www.mytestshop.fi/pay/return/Error.do?pmt_id=1998524_1 http://www.mytestshop.fi/pay/return/Error.do?paid=0&pmt_id=1998524_1 Mikäli Maksuturvan maksutavan valintasivu on ohitettu, palautetaan joissakin tapauksissa virhevastauksen perässä tieto pyynnössä olleista virheellisistä parametreista. Virheellinen tarkiste: http://www.mytestshop.fi/pay/return/Error.do?pmt_id=1998524_1&error_fields=[generic][pmt_hash] Virheellinen maksajan sähköpostiosoite: http://www.mytestshop.fi/pay/return/Error.do?pmt_id=1998524_1&error_fields=[model.pmt_buyeremail] Virheellinen toimitusosoitteen postinumero: http://www.mytestshop.fi/pay/return/Error.do? pmt_id=1998524_1&error_fields=[model.pmt_deliverypostalcode] Virheelliset maksajan sähköpostiosoite, laskutusosoitteen postinumero ja toimitusosoitteen postinumero: http://www.mytestshop.fi/pay/return/Error.do?pmt_id=1998524_1\ &error_fields=[model.pmt_buyeremail][model.pmt_buyerpostalcode] [model.pmt_deliverypostalcode] Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 114 / 129 Maksuturvan maksupalvelun integrointiohjeet 5.3.1 Esimerkki maksusanoman koostamisesta ja tarkisteenlaskennasta (PHP) Alla esitellään hyvin pintapuolisesti maksusanoman koostaminen verkkokauppasovelluksessa vaiheittain. Esimerkit pohjautuvat Maksuturvan PrestaShop-maksumoduuliin, mutta niitä on yksinkertaistettu selkeyden vuoksi. Todellisissa integraatioissa tulee myös aina huomioida verkkokauppaan syötettyjen ja verkkokaupan välittämien tietojen tarkistus, käytetty merkistökoodaus ym. Erityisesti on kiinnitettävä huomiota verkkokaupan salaisen avaimen tallentamiseen, säilyttämiseen ja käyttöön. Salaista avainta ei saa koskaan välittää minkään viestin osana. Salaista avainta käytetään ainoastaan muodostettaessa merkistöjonoa, josta tarkiste lasketaan. Kyseistä merkkijonoa ei tule milloinkaan näyttää selväkielisessä muodossa. Muuttumattomat aputaulukot / -listat Katso tietueiden tarkat listat ja määritteet maksamisen rajapintakuvauksesta. Maksusanoman pakollisten tietueiden (poislukien hash) lista protected $_compulsoryData = array( 'pmt_action', 'pmt_version', 'pmt_sellerid', 'pmt_id', 'pmt_orderid', ... 'pmt_hashversion', 'pmt_keygeneration' ); Maksusanoman valinnaisten tietueiden lista protected $_optionalData = array( 'pmt_selleriban', 'pmt_userlocale', ... 'pmt_buyeremail', ); Tuoterivien pakollisten tietueiden lista protected $_rowCompulsoryData = array( 'pmt_row_name', ... 'pmt_row_discountpercentage', 'pmt_row_type', ); Tuoterivien valinnaisten tietueiden lista protected $_rowOptionalData = array( 'pmt_row_articlenr', 'pmt_row_unit', ); Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 115 Tarkisteeseen sisällytettävät tietueet: HUOM: lista koottu juuri rajapinnan kuvaamassa järjestyksessä protected $_hashData = array( 'pmt_action', 'pmt_version', 'pmt_selleriban', 'pmt_id', ... 'pmt_sellercosts' ); $order_data_returned_from_store; // verkkokaupan palauttama tilauksen sisältö, array() 1. Tilauksen tietojen tarkistus (merkkimäärät, tyypit jne.) Eli validoidaan $order_data_returned_from_store pakollisten ja valinnaisten tietueiden listoja vasten. 2. Koostetaan rivitiedot $order = $order_data_returned_from_store->items(); // verkkokaupan palauttama tilauksen sisältö, array() $orderAmount = 0; // sum of rows of types 1, 4, 5, 6 $products_rows = array(); // Lisätään tavalliset tuotteet foreach ($order->getProducts() as $product) { $orderAmount += $product["total_price_including_vat"]; $row = array( 'pmt_row_name' => $product["name"], 'pmt_row_desc' => $product["desc"], 'pmt_row_quantity' => $product["cart_quantity"], 'pmt_row_articlenr' => $product["reference"], 'pmt_row_deliverydate' => date("d.m.Y"), 'pmt_row_price_net' => $product["price_excluding_vat"], 'pmt_row_vat' => $product["rate"], 'pmt_row_discountpercentage' => $product["discount"], 'pmt_row_type' => 1; ); array_push($products_rows, $row); } // Lisätään toimituskulut $sellerCosts = $order_summary['total_shipping']; $carrier = $order->id_carrier; // Adding the shipping cost as a row $row = array( 'pmt_row_name' => $carrier->name, 'pmt_row_desc' => $carrier->name, Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] / 129 116 / 129 Maksuturvan maksupalvelun integrointiohjeet 'pmt_row_quantity' => 1, 'pmt_row_deliverydate' => date("d.m.Y"), 'pmt_row_price_net' => $order_summary['total_shipping'])), 'pmt_row_vat' => $shippingVat, 'pmt_row_discountpercentage' => $shipping_discount, 'pmt_row_type' => 2, ); array_push($products_rows, $row); // Näiden jälkeen lisätään myös käsittelykulut, räätälöidyt tuotteet, palvelusuoritukset // ja alennusrivit kuten yllä, mutta 'pmt_row_type' vastaavilla numeroilla 3. Koostetaan koko tilaus $order_data = array( "pmt_keygeneration" "pmt_sellerid" => get('MAKSUTURVA_SECRET_KEY_VERSION'), => get('MAKSUTURVA_SELLER_ID'), "pmt_id" "pmt_orderid" "pmt_reference" => {yksilöivä maksutapahtuman tunniste}, => {tilausnumero}, => {viitenumero}, ... "pmt_paymentmethod" => {maksutavan tunnus}, // esivalittu maksutapa (valinnainen) // Customer Information "pmt_buyername" => $order_summary["billing"]->firstname . " " . $order_summary["billing"]->lastname, "pmt_buyeraddress" => $order_summary["billing"]->address, ... // Delivery information "pmt_deliveryname" => $order_summary["delivery"]->firstname . " " . $order_summary["delivery"]->lastname, "pmt_deliveryaddress" => $order_summary["delivery"]->address, ... // Escrow (Tyytyväisyystakuu vs. Suoramaksu) "pmt_escrow" => "Y", // jos käytössä Tyytyväisyystakuu-palvelu, niin "Y", suoramaksupalvelussa "N" ); "pmt_order_amount" "pmt_sellercosts" => $order_amount, => $sellerCosts, "pmt_rows" "pmt_rows_data" => count($products_rows), => $products_rows 4. Tarkisteen muodostaminen protected function generateHash() { $hashString = ''; // Käydään järjestyksessä läpi tarkisteeseen sisällytettävien tietueiden listaa ja lisätään tilaustiedoista Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet // niiden arvot tilaustiedoista merkkijonoon, josta tarkiste lasketaan. // valinnaisten parametrien arvot lisätään vain, jos ne esiintyvät tilaustiedoissa foreach ($_hashData as $hash_data_parameter_name) { switch ($hash_data_parameter_name) { case 'pmt_selleriban': case 'pmt_invoicefromseller': case 'pmt_paymentmethod': case 'pmt_buyeridentificationcode': if (in_array($hash_data_parameter_name, array_keys($order_data))) { $hashString .= $order_data[$hash_data_parameter_name] . '&'; } break; default: $hashString .= $order_data[$hash_data_parameter_name] . '&'; } } foreach ($order_data['pmt_rows_data'] as $order) { foreach ($order as $data) { $hashString .= $data . '&'; } } $hashString .= get('MAKSUTURVA_SECRET_KEY') . '&'; } return hash({valittu hash algoritmi}, $hashString); 5. Muodostetaan datasta maksusanoma $url = ""; foreach ($order_data as $key => $data) { if ($key == 'pmt_rows_data') { $rowCount = 1; foreach ($data as $rowData) { foreach ($rowData as $rowKey => $rowInnerData) { $url .= $rowKey . $rowCount . '=' . $rowInnerData . '&'; } $rowCount++; } } else { $url .= $key . '=' . $data . '&'; } } $url .= 'pmt_hash='.generateHash(); return $url; Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 117 / 129 118 / 129 Maksuturvan maksupalvelun integrointiohjeet 5.4 Maksutapahtuman tilan kysely Esimerkki pyynnöstä (HTTP POST) <form method="post" action="http://test1.maksuturva.fi/PaymentStatusQuery.pmt"> <input type="text" name="pmtq_action" value="PAYMENT_STATUS_QUERY" /> <input type="text" name="pmtq_version" value="0005" /> <input type="text" name="pmtq_sellerid" value="ABC123DE" /> <input type="text" name="pmtq_id" value="1998524_1" /> <input type="text" name="pmtq_resptype" value="XML" /> <input type="text" name="pmtq_hashversion" value="SHA-256" /> <input type="text" name="pmtq_hash" value="6E496757BEA05DACEEEC625E9FCD12802AF67D189F311DAF372BB618A17341A3" /> <input type="text" name="pmtq_keygeneration" value="1" /> </form> Esimerkkejä vastauksista (HTTP RESPONSE) Tapahtumaa ei löydy tai sitä ei ole maksettu: <pmtq> <pmtq_returncode>00</pmtq_returncode> <pmtq_returntext>No payment found with specified data</pmtq_returntext> <pmtq_action>PAYMENT_STATUS_QUERY</pmtq_action> <pmtq_id>1998524_1</pmtq_id> <pmtq_amount>0,00</pmtq_amount> <pmtq_hash>7FC9C32FC4FCD351AC0C10CFA1A69C7D4D6BB17EAC972B44F084E8E0DE452DAE</pmtq_hash> <pmtq_sellerid>ABC123DE</pmtq_sellerid> <pmtq_version>0005</pmtq_version> </pmtq> Tapahtumaa ei ole maksettu: Ostaja saattaa olla vielä esim. pankissa suorittamassa maksuaan. <pmtq> <pmtq_returntext>No payment found with specified data</pmtq_returntext> <pmtq_paymentmethod>FI01</pmtq_paymentmethod> <pmtq_amount>568,10</pmtq_amount> <pmtq_paymentstarttimestamp>15.10.2014 14:16:48</pmtq_paymentstarttimestamp> <pmtq_returncode>00</pmtq_returncode> <pmtq_certification>N</pmtq_certification> <pmtq_action>PAYMENT_STATUS_QUERY</pmtq_action> <pmtq_id>1998524_1</pmtq_id> <pmtq_escrow>Y</pmtq_escrow> <pmtq_hash>A217E028A693141DB445ED7A6A70646116F28E973B822254CAAFB18EA89EF912</pmtq_hash> <pmtq_sellerid>ABC123DE</pmtq_sellerid> <pmtq_sellercosts>5,00</pmtq_sellercosts> <pmtq_version>0005</pmtq_version> </pmtq> Tapahtuma on maksettu (Tyytyväisyystakuu-palvelu): Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet <pmtq> <pmtq_paymentdate>15.10.2014</pmtq_paymentdate> <pmtq_returntext>Paid and missing tracking code</pmtq_returntext> <pmtq_paymentmethod>FI01</pmtq_paymentmethod> <pmtq_amount>568,10</pmtq_amount> <pmtq_paymentstarttimestamp>15.10.2014 14:16:48</pmtq_paymentstarttimestamp> <pmtq_returncode>20</pmtq_returncode> <pmtq_certification>Y</pmtq_certification> <pmtq_action>PAYMENT_STATUS_QUERY</pmtq_action> <pmtq_id>1998524_1</pmtq_id> <pmtq_escrow>Y</pmtq_escrow> <pmtq_hash>3CAB3D9EA0C83EF9FCB843ECF864FC5111BDBC81AD66AF990E3105760C29CF6A</pmtq_hash> <pmtq_sellerid>ABC123DE</pmtq_sellerid> <pmtq_sellercosts>5,00</pmtq_sellercosts> <pmtq_version>0005</pmtq_version> </pmtq> Tapahtuma on maksettu ja toimitustiedot annettu (Tyytyväisyystakuu-palvelu): <pmtq> <pmtq_paymentdate>15.10.2014</pmtq_paymentdate> <pmtq_returntext>Paid, being delivered and uncompensated</pmtq_returntext> <pmtq_paymentmethod>FI01</pmtq_paymentmethod> <pmtq_amount>568,10</pmtq_amount> <pmtq_paymentstarttimestamp>15.10.2014 14:16:48</pmtq_paymentstarttimestamp> <pmtq_returncode>30</pmtq_returncode> <pmtq_trackingcodes>[ITELL|JJFI12345678901234567|00]</pmtq_trackingcodes> <pmtq_certification>Y</pmtq_certification> <pmtq_action>PAYMENT_STATUS_QUERY</pmtq_action> <pmtq_id>1998524_1</pmtq_id> <pmtq_escrow>Y</pmtq_escrow> <pmtq_hash>4BC6BFA68A44CB0A432340FEE90B90C9844C466288FD9FFC260CEAFB4DAD3320</pmtq_hash> <pmtq_sellerid>ABC123DE</pmtq_sellerid> <pmtq_sellercosts>5,00</pmtq_sellercosts> <pmtq_version>0005</pmtq_version> </pmtq> Tapahtuma on tilitetty verkkokaupalle: <pmtq> <pmtq_paymentdate>15.10.2014</pmtq_paymentdate> <pmtq_returntext>Compensated to the seller</pmtq_returntext> <pmtq_paymentmethod>FI01</pmtq_paymentmethod> <pmtq_amount>568,10</pmtq_amount> <pmtq_paymentstarttimestamp>15.10.2014 14:16:48</pmtq_paymentstarttimestamp> <pmtq_returncode>40</pmtq_returncode> <pmtq_trackingcodes>[ITELL|JJFI12345678901234567|80]</pmtq_trackingcodes> <pmtq_certification>Y</pmtq_certification> <pmtq_action>PAYMENT_STATUS_QUERY</pmtq_action> <pmtq_id>1998524_1</pmtq_id> <pmtq_escrow>Y</pmtq_escrow> <pmtq_hash>1A26625AB05E7CBCFB148894BE77AC498ED852D4526005F03B3E76791F4D3ACC</pmtq_hash> Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 119 / 129 120 / 129 Maksuturvan maksupalvelun integrointiohjeet <pmtq_sellerid>ABC123DE</pmtq_sellerid> <pmtq_sellercosts>5,00</pmtq_sellercosts> <pmtq_version>0005</pmtq_version> </pmtq> Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 5.5 Toimitustietojen hallinta Esimerkkejä toimitustiedon lisäämispyynnöistä: Lisätään ensimmäinen Postin lähetystunnus, mutta ei viimeinen (pkg_allsent=N): <form action="http://test1.maksuturva.fi/addDeliveryInfo.pmt"> <input type="hidden" name="pkg_version" value="0002"> <input type="hidden" name="pkg_sellerid" value="ABC123DE"> <input type="hidden" name="pkg_id" value="1998524_1"> <input type="hidden" name="pkg_deliverymethodid" value="ITELL"> <input type="hidden" name="pkg_adddeliveryinfo" value="JJFI12345612345123456"> <input type="hidden" name="pkg_allsent" value="N"> <input type="hidden" name="pkg_forceupdate" value="N"> <input type="hidden" name="pkg_resptype" value="HTML"> <!--<input type="hidden" name="pkg_return" value="">--> <input type="hidden" name="pkg_hashversion" value="SHA-256"> <input type="hidden" name="pkg_hash" value="CFDDF22DD538FFECF6F784F5E10C88A3704ED597E700DE6A36979D868574B8C4"> <input type="hidden" name="pkg_keygeneration" value="1"> <input type="submit" value="Add delivery info"> </form> Lisätään ensimmäinen ja viimeinen (pkg_allsent=Y) Postin lähetystunnus: <form action="http://test1.maksuturva.fi/addDeliveryInfo.pmt"> <input type="hidden" name="pkg_version" value="0002"> <input type="hidden" name="pkg_sellerid" value="ABC123DE"> <input type="hidden" name="pkg_id" value="1998524_1"> <input type="hidden" name="pkg_deliverymethodid" value="ITELL"> <input type="hidden" name="pkg_adddeliveryinfo" value="JJFI12345612345123456"> <input type="hidden" name="pkg_allsent" value="Y"> <input type="hidden" name="pkg_forceupdate" value="N"> <input type="hidden" name="pkg_resptype" value="HTML"> <!--<input type="hidden" name="pkg_return" value="">--> <input type="hidden" name="pkg_hashversion" value="SHA-256"> <input type="hidden" name="pkg_hash" value="CA40867A33B5E6ACD525F89E398970A98C73F83AF9D02EAECCAFE2E2E92636E1"> <input type="hidden" name="pkg_keygeneration" value="1"> <input type="submit" value="Add delivery info"> </form> Esimerkkejä lisäyspyynnön vastauksista: OK-vastaus: <pmtq> <pkg_resultcode>00</pkg_resultcode> <pkg_version>0002</pkg_version> <pkg_hash>9CDDD56A2E2756818D1E029153CD8DF7A6DD4ACE33296FB2CB5948AF3D5BA4AC</pkg_hash> <pkg_resulttext>OK</pkg_resulttext> Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 121 / 129 122 / 129 Maksuturvan maksupalvelun integrointiohjeet <pkg_sellerid>ABC123DE</pkg_sellerid> <pkg_id>1998524_1</pkg_id> </pmtq> Parametri pkg_id uupui pyynnöstä: <pmtq> <pkg_resultcode>99</pkg_resultcode> <pkg_version>0002</pkg_version> <pkg_hash>null</pkg_hash> <pkg_resulttext>pkg_id is a mandatory field</pkg_resulttext> <pkg_sellerid>ABC123DE</pkg_sellerid> <pkg_id/> </pmtq> Parametri pkg_hash oli virheellinen eli verkkokaupan välittämä pkg_hash ei täsmännyt Maksuturvan laskeman tarkisteen kanssa: <pmtq> <pkg_resultcode>99</pkg_resultcode> <pkg_version>0002</pkg_version> <pkg_hash>null</pkg_hash> <pkg_resulttext>pkg_hash did not pass validation</pkg_resulttext> <pkg_sellerid>ABC123DE</pkg_sellerid> <pkg_id>1998524_1</pkg_id> </pmtq> Esimerkki toimitustiedon muutospyynnöstä: <form action="http://test1.maksuturva.fi/updateDeliveryInfo.pmt"> <input type="hidden" name="pkg_version" value="0002"> <input type="hidden" name="pkg_sellerid" value="ABC123DE"> <input type="hidden" name="pkg_id" value="1998524_1"> <input type="hidden" name="pkg_deliverymethodid" value="ITELL"> <input type="hidden" name="pkg_remdeliverymethod" value="JJFI12345612345123456"> <input type="hidden" name="pkg_adddeliveryinfo" value="JJFI12345612345234567"> <input type="hidden" name="pkg_allsent" value="N"> <input type="hidden" name="pkg_forceupdate" value="N"> <input type="hidden" name="pkg_resptype" value="XML"> <!--<input type="hidden" name="pkg_return" value="">--> <input type="hidden" name="pkg_hashversion" value="SHA-256"> <input type="hidden" name="pkg_hash" value="0B7591FAB0B9ED72FBDBB8B99F6C92BB82043BB03F056B4400BF71D71A939EC0"> <input type="hidden" name="pkg_keygeneration" value="1"> <input type="submit" value="Update delivery info"> </form> Esimerkki muutospyynnön vastauksesta: <pmtq> <pkg_resultcode>00</pkg_resultcode> <pkg_version>0002</pkg_version> <pkg_hash>CFDDF22DD538FFECF6F784F5E10C88A3704ED597E700DE6A36979D868574B8C4</pkg_hash> Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet <pkg_resulttext>OK</pkg_resulttext> <pkg_sellerid>ABC123DE</pkg_sellerid> <pkg_id>1998524_1</pkg_id> </pmtq> Esimerkki toimitustiedon poistopyynnöstä: <form action="http://test1.maksuturva.fi/deleteDeliveryInfo.pmt"> <input type="hidden" name="pkg_version" value="0002"> <input type="hidden" name="pkg_sellerid" value="ABC123DE"> <input type="hidden" name="pkg_id" value="1998524_1"> <input type="hidden" name="pkg_deliverymethodid" value="ITELL"> <input type="hidden" name="pkg_remdeliverymethod" value="JJFI12345612345234567"> <input type="hidden" name="pkg_allsent" value="N"> <input type="hidden" name="pkg_forceupdate" value="N"> <input type="hidden" name="pkg_resptype" value="XML"> <!--<input type="hidden" name="pkg_return" value="">--> <input type="hidden" name="pkg_hashversion" value="SHA-256"> <input type="hidden" name="pkg_hash" value="CA40867A33B5E6ACD525F89E398970A98C73F83AF9D02EAECCAFE2E2E92636E1"> <input type="hidden" name="pkg_keygeneration" value="1"> <input type="submit" value="Delete delivery info"> </form> Esimerkki poistopyynnön vastauksesta: <pmtq> <pkg_resultcode>00</pkg_resultcode> <pkg_version>0002</pkg_version> <pkg_hash>CFDDF22DD538FFECF6F784F5E10C88A3704ED597E700DE6A36979D868574B8C4</pkg_hash> <pkg_resulttext>OK</pkg_resulttext> <pkg_sellerid>ABC123DE</pkg_sellerid> <pkg_id>1998524_1</pkg_id> </pmtq> Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 123 / 129 124 / 129 Maksuturvan maksupalvelun integrointiohjeet 5.6 Maksutapahtuman muuttaminen Esimerkkejä pyynnöistä (HTTP POST) Koko tilauksen peruutuspyyntö: <form method="post" action="http://test1.maksuturva.fi/PaymentCancel.pmt"> <input type="hidden" name="pmtc_action" value="CANCEL" /> <input type="hidden" name="pmtc_version" value="0005" /> <input type="hidden" name="pmtc_sellerid" value="ABC123DE" /> <input type="hidden" name="pmtc_id" value="1998524_1" /> <input type="hidden" name="pmtc_amount" value="568,10" /> <input type="hidden" name="pmtc_currency" value="EUR" /> <input type="hidden" name="pmtc_canceltype" value="FULL_REFUND" /> <input type="hidden" name="pmtc_canceldescription" value="Valitettavasti tuotteet olivat päässeet loppumaan varastosta." /> <input type="hidden" name="pmtc_cancelreason" value="OUTOF" /> <input type="hidden" name="pmtc_resptype" value="XML" /> <input type="hidden" name="pmtc_hashversion" value="SHA-256" /> <input type="hidden" name="pmtc_hash" value="C1F6CBA732E925C15E7B42238ED4FEA31DAA54BE53BE6A09748DF4F8EAC94269" /> <input type="hidden" name="pmtc_keygeneration" value="1" /> <input type="submit" value="Lähetä peruutussanoma" /> </form> 150,00 € suuruinen hyvityspyyntö (Hinnan korjaus): <form method="post" action="http://test1.maksuturva.fi/PaymentCancel.pmt"> <input type="hidden" name="pmtc_action" value="CANCEL" /> <input type="hidden" name="pmtc_version" value="0005" /> <input type="hidden" name="pmtc_sellerid" value="ABC123DE" /> <input type="hidden" name="pmtc_id" value="1998524_1" /> <input type="hidden" name="pmtc_amount" value="568,10" /> <input type="hidden" name="pmtc_currency" value="EUR" /> <input type="hidden" name="pmtc_canceltype" value="PARTIAL_REFUND" /> <input type="hidden" name="pmtc_cancelamount" value="150,00" /> <input type="hidden" name="pmtc_canceldescription" value="Hyvitys siitä, että toimitusaika venähti lupauksistamme huolimatta." /> <input type="hidden" name="pmtc_cancelreason" value="OTHER" /> <input type="hidden" name="pmtc_resptype" value="XML" /> <input type="hidden" name="pmtc_hashversion" value="SHA-256" /> <input type="hidden" name="pmtc_hash" value="3BB641AD9F2A26CCFBDAA36E58D25F011A9721D8F47570B07A7EBEE4DBE9F14F" /> <input type="hidden" name="pmtc_keygeneration" value="1" /> <input type="submit" value="Lähetä peruutussanoma" /> </form> 123,00 € suuruinen tuotepalautuspyyntö (Osapalautus): Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 125 / 129 <form method="post" action="http://test1.maksuturva.fi/PaymentCancel.pmt"> <input type="hidden" name="pmtc_action" value="CANCEL" /> <input type="hidden" name="pmtc_version" value="0005" /> <input type="hidden" name="pmtc_sellerid" value="ABC123DE" /> <input type="hidden" name="pmtc_id" value="1998524_1" /> <input type="hidden" name="pmtc_amount" value="568,10" /> <input type="hidden" name="pmtc_currency" value="EUR" /> <input type="hidden" name="pmtc_canceltype" value="PARTIAL_REFUND_AND_RETURN_OF_DELIVERIES" /> <input type="hidden" name="pmtc_cancelamount" value="123,00" /> <input type="hidden" name="pmtc_canceldescription" value="Ostaja palauttaa toisen tilaamistaan tuote A:sta" /> <input type="hidden" name="pmtc_cancelreason" value="DEFEC" /> <input type="hidden" name="pmtc_resptype" value="XML" /> <input type="hidden" name="pmtc_hashversion" value="SHA-256" /> <input type="hidden" name="pmtc_hash" value="E6495B9E0C05BE827F5BE97FA371193B793F59B4F2A4068165BD4DAEBA96E6F7" /> <input type="hidden" name="pmtc_keygeneration" value="1" /> <input type="submit" value="Lähetä peruutussanoma" /> </form> Esimerkkejä XML-vastauksista (HTTP RESPONSE) OK-vastaus: <pmtc> <pmtc_action>CANCEL</pmtc_action> <pmtc_version>0005</pmtc_version> <pmtc_sellerid>ABC123DE</pmtc_sellerid> <pmtc_id>1998524_1</pmtc_id> <pmtc_returncode>00</pmtc_returncode> <pmtc_returntext>Cancel received succesfully</pmtc_returntext> <pmtc_hash>E8343D1E9995854BA4A13BE5B6FB4E4DD61A362BE682336CA7A10145BC77FFEC</pmtc_hash> </pmtc> Pyynnöstä puuttui palautettava rahamäärä, vaikka peruutuksen tyyppi oli esim. PARTIAL_REFUND: <pmtc> <pmtc_action>CANCEL</pmtc_action> <pmtc_version>0005</pmtc_version> <pmtc_sellerid>ABC123DE</pmtc_sellerid> <pmtc_id>1998524_1</pmtc_id> <pmtc_returncode>90</pmtc_returncode> <pmtc_returntext>Errors in input data, specified in element errors</pmtc_returntext> <errors> <error name="pmtc_cancelamount" type="field">pmtc_cancelamount is invalid</error> </errors> </pmtc> Pyynnössä oli virheellinen tarkiste: Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 126 / 129 Maksuturvan maksupalvelun integrointiohjeet <pmtc> <pmtc_action>CANCEL</pmtc_action> <pmtc_version>0005</pmtc_version> <pmtc_sellerid>ABC123DE</pmtc_sellerid> <pmtc_id>1998524_1</pmtc_id> <pmtc_returncode>90</pmtc_returncode> <pmtc_returntext>Errors in input data, specified in element errors</pmtc_returntext> <errors> <error name="pmtc_hash" type="field">pmtc_hash is invalid</error> </errors> </pmtc> Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 5.7 Tilitysraporttien hakeminen Esimerkkejä tilitysraporttipyynnöstä (HTTP POST) Pyyntö 14.10.2014 tehdyistä tilityksistä: <form method="post" action="http://test1.maksuturva.fi/GetCompensationsByTimeInterval.pmt"> <input type="hidden" name="gc_action" value="GET_COMPENSATIONS" /> <input type="hidden" name="gc_version" value="0001" /> <input type="hidden" name="gc_sellerid" value="ABC123DE" /> <input type="hidden" name="gc_begindate" value="14.10.2014" /> <input type="hidden" name="gc_enddate" value="14.10.2014" /> <input type="hidden" name="gc_hashversion" value="SHA-256" /> <input type="hidden" name="gc_keygeneration" value="001" /> <input type="hidden" name="gc_hash" value="CFDDF22DD538FFECF6F784F5E10C88A3704ED597E700DE6A36979D868574B8C4" /> <input type="submit" value="Hae raportti"> </form> Esimerkkejä XML-vastauksista (HTTP RESPONSE) OK-vastaus, jossa yksi verkkokaupan alkuperäisellä viitteellä tilitetty tapahtuma: <ns2:getCompensationsResponse xmlns:ns2="https://www.maksuturva.fi/smtschema/ GetCompensationsResponse.xsd"> <version>0001</version> <timestamp>2014-10-16T14:14:51.000+03:00</timestamp> <sellerId>ABC123DE</sellerId> <resultCode>00</resultCode> <resultText>OK</resultText> <hashVersion>SHA-256</hashVersion> <keyGeneration>1</keyGeneration> <hash>9B7ADF7633688101301E8F7617E996777D329A390F56FD135BE0122C46745BEC</hash> <compensations> <compensation> <compensationType>SINGLE</compensationType> <compensationDate>2014-10-14T00:00:00.000+03:00</compensationDate> <reference>00000001234567890120</reference> <grossAmount>573.1</grossAmount> <netAmount>564.31</netAmount> <refundedAmount>0</refundedAmount> <commission>8.79</commission> <orders> <order> <orderNumber>1998524</orderNumber> <originalReference>1234567890120</originalReference> <paymentId>1998524_1</paymentId> <sellerGrossAmount>573.1</sellerGrossAmount> <sellerNetAmount>564.31</sellerNetAmount> <refundedAmount>0</refundedAmount> <commission>8.79</commission> Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] 127 / 129 128 / 129 Maksuturvan maksupalvelun integrointiohjeet <buyerPaymentDateTime>2014-09-27T00:00:00.000+03:00</buyerPaymentDateTime> </order> </orders> </compensation> </compensations> </ns2:getCompensationsResponse> OK-vastaus, jossa on yksi koontitilitys kiinteällä viitteellä 1232, joka sisältää kaksi tapahtumaa: <ns2:getCompensationsResponse xmlns:ns2="https://www.maksuturva.fi/smtschema/ GetCompensationsResponse.xsd"> <version>0001</version> <timestamp>2014-10-16T14:27:26.000+03:00</timestamp> <sellerId>ABC123DE</sellerId> <resultCode>00</resultCode> <resultText>OK</resultText> <hashVersion>SHA-256</hashVersion> <keyGeneration>1</keyGeneration> <hash>E7BE30D784E97F98673E28F2570CF69AEE03810BE51E5EA773FD0E6ADAC99547</hash> <compensations> <compensation> <compensationCode>10000000000000000000</compensationCode> <compensationType>BUNDLE</compensationType> <compensationDate>2014-10-14T14:27:12.000+03:00</compensationDate> <reference>00000000000000001232</reference> <grossAmount>1146.20</grossAmount> <netAmount>1051.44</netAmount> <refundedAmount>0.00</refundedAmount> <commission>94.76</commission> <orders> <order> <bundleCode>10000000000000000000</bundleCode> <orderNumber>1998524</orderNumber> <originalReference>19985242</originalReference> <paymentId>1998524_1</paymentId> <sellerGrossAmount>573.1</sellerGrossAmount> <sellerNetAmount>564.31</sellerNetAmount> <refundedAmount>0</refundedAmount> <commission>8.79</commission> <buyerPaymentDateTime>2014-09-27T00:00:00.000+03:00</buyerPaymentDateTime> </order> <order> <bundleCode>10000000000000000000</bundleCode> <orderNumber>2000301</orderNumber> <originalReference>20003016</originalReference> <paymentId>2000301_1</paymentId> <sellerGrossAmount>573.1</sellerGrossAmount> <sellerNetAmount>487.13</sellerNetAmount> <refundedAmount>0</refundedAmount> <commission>85.97</commission> <buyerPaymentDateTime>2014-09-30T00:00:00.000+03:00</buyerPaymentDateTime> </order> </orders> Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] Maksuturvan maksupalvelun integrointiohjeet 129 </compensation> </compensations> </ns2:getCompensationsResponse> Pyydetyltä aikaväliltä ei löydetty yhtään tilitystä: <ns2:getCompensationsResponse xmlns:ns2="https://www.maksuturva.fi/smtschema/ GetCompensationsResponse.xsd"> <timestamp>2014-10-16T14:09:17.000+03:00</timestamp> <sellerId>ABC123DE</sellerId> <resultCode>95</resultCode> <resultText>No events found.</resultText> <keyGeneration>1</keyGeneration> </ns2:getCompensationsResponse> Pyydetty päivämääräväli oli liian suuri: <ns2:getCompensationsResponse xmlns:ns2="https://www.maksuturva.fi/smtschema/ GetCompensationsResponse.xsd"> <timestamp>2014-10-16T14:07:45.000+03:00</timestamp> <sellerId>ABC123DE</sellerId> <resultCode>95</resultCode> <resultText>Errors in: {[gc_enddate:the given interval is too big. Maximum allowed is one month.]}</resultText> <keyGeneration>1</keyGeneration> </ns2:getCompensationsResponse> Suomen Maksuturva Oy Ruoholahdenkatu 23 | FIN-00180 Helsinki, Finland | [email protected] / 129