Maksuturva- ja emaksut- palvelun integrointiohje Versio 1.4
INTEGROINTIOHJE 2(9) Sisältö 1 INTEGROINTIMAHDOLLISUUDET... 3 2 INTEGROINTIRAJAPINNAT... 4 2.1 Yleistä... 4 2.2 MAKSUTURVA/EMAKSUT-TAPAHTUMAN KÄSITTELY... 4 2.2.1 Maksaminen (Maksuturva ja emaksut)... 4 2.2.2 Tapahtuman tilan kysely (Maksuturva ja emaksut)... 5 2.2.3 Toimitustietojen hallinta (vain Maksuturva)... 5 2.2.4 Tapahtuman peruutus (vain Maksuturva)... 5 2.3 MAKSUTURVA-/EMAKSUT-PALVELUN KÄYTTÖÖNOTTO (LOMAKE)... 5 3 TARKISTEEN LASKENTA... 6 4 VASTAUSTEN KÄSITTELY... 7 4.1 Vastauksen tietojen tarkistaminen... 7 5 TESTAUS... 7 5.1 Testiympäristö omilla testitunnuksilla... 7 5.2 Rajapintatestaus yleisellä testitunnuksella tuotantoympäristössä... 7 5.2.1 Maksamisen testaus (Maksuturva ja emaksut)... 8 5.2.2 Tapahtuman tilan kyselyn testaus (Maksuturva ja emaksut)... 8 5.2.3 Toimitustietojen hallinnan testaus (vain Maksuturva)... 8 5.2.4 Tapahtuman peruutus (vain Maksuturva)... 8 6 MATERIAALIT... 9 6.1 MAKSUTURVA... 9 6.2 EMAKSUT... 9
INTEGROINTIOHJE 3(9) 1 INTEGROINTIMAHDOLLISUUDET Maksuturva-/eMaksut-palvelun käyttö ja integrointi vastaa pitkälti pankkien verkkomaksupainikkeita. Maksuturva tarjoaa rajapinnat kaikkeen toimeksiannon käsittelyyn. emaksut-palvelua koskevat palvelun tilaus-, maksaminen ja tilan kysely -palvelurajapinnat. Maksuturva- ja emaksut-palvelu tarjoaa vaihtoehtona verkkokauppiaiden käyttöön KauppiasExtranetkäyttöliittymän, jonka kautta voi hoitaa myös Maksuturva-palvelun tapauksessa tapahtumiin liittyvät päivitykset, eli toimitustietojen hallinnan sekä peruutus- ja palautuskäsittelyt. Uusia maksuja voi tulla vain rajapinnan kautta. Tapahtumakäsittelyn lisäksi Maksuturva tarjoaa rajapinnan myös palvelun automaattiseen käyttöönottoon verkkokauppaohjelmistosta. Mitä useampi rajapinta on käytössä verkkokauppaohjelmiston kautta, sen helppokäyttöisempi se on verkkokauppiaalle. Jos verkkokauppaohjelmistossa on kaikki tapahtuman käsittelyyn liittyvät rajapinnat käytössä, verkkokauppiaan ei tarvitse käsitellä yksittäisiä Maksuturva-tapahtumia KauppiasExtranetin kautta, vaan Maksuturva-tapahtumat päivittyvät tilauksen päivityksen yhteydessä.
INTEGROINTIOHJE 4(9) HUOM! Vaikka Maksuturva ja emaksut voidaan teknisesti integroida samoilla rajapinnoilla (Maksaminen ja Tapahtuman tilan kysely), käyttäjille maksutavat tulee kuitenkin näyttää omina erillisinä maksutapoina verkkokauppaohjelmistoalustan asetuksissa (myyjälle) ja maksuvalintasivulla (ostajalle). 2 INTEGROINTIRAJAPINNAT 2.1 Yleistä Maksuturvan/eMaksut-palvelun rajapinnat toimivat niin, että verkkokauppa välittää rajapinnan tiedot FORM-tietoryhmässä piilomuuttujina. Mikäli sivusto pyörii esim. Apache -palvelimella, joka tarjoilee sivut UTF-8 -muodossa, pitää FORMille laittaa seuraava attribuutti: accept-charset= ISO-8859-1. Muussa tapauksessa skandinaaviset merkit eivät välity oikein. Tiedot lähetetään rajapintakohtaiseen osoitteeseen: https://www.maksuturva.fi/ rajapinta.pmt. Osoite näkyy rajapintakohtaisista kuvauksista. Rajapintakohtaisesta kuvauksesta käy ilmi rajapinnan tietokentät, niiden muoto, selite ja pakollisuus. Myös vastaussanoman tiedot on kuvattu vastaavasti. 2.2 MAKSUTURVA/EMAKSUT-TAPAHTUMAN KÄSITTELY 2.2.1 Maksaminen (Maksuturva ja emaksut) Palvelussa otetaan vastaan uusi maksu, eli Maksuturva-/eMaksut-toimeksianto. Asiakas maksaa Maksuturva-/eMaksut-palvelussa valitulla tavalla ja tulos käy ilmi siitä, mihin vastausosoitteeseen vastaussanoma ohjautuu: ok-osoite: maksu on maksettu viivästetty maksu -osoite: maksaja vahvisti toimeksiannon ja aikoo maksaa tilisiirrolla (maksua ei ole vielä rekisteröity). HUOM! Tilisiirtoa ei tueta enää nykyisissä valmispaketeissa. peruutus- tai virheosoite: maksaminen keskeytettiin tai se keskeytyi virheeseen pmt_escrow -parametrin arvo määrittää käytetyn palvelun: Maksuturva: pmt_escrow = Y emaksut: pmt_escrow = N Rajapinnan kuvaus: SMT_Rajapinnat_Maksaminen_vx.x.pdf (x.x on versionumero).
INTEGROINTIOHJE 5(9) 2.2.2 Tapahtuman tilan kysely (Maksuturva ja emaksut) Palvelusta voi tarkistaa Maksuturva-/eMaksut-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 kauppiaan tulee peruuttaa toimeksianto (vastauskoodi 91) Rajapinnan kuvaus: SMT_Rajapinnat_TapahtumanTilanKysely_vx.x.pdf (x.x on versionumero). 2.2.3 Toimitustietojen hallinta (vain Maksuturva) 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. Vastaussanomasta tulee vähintään tarkistaa, onnistuiko toimitustapojen päivitys (vastauskoodi 10). Rajapinnan kuvaus: SMT_Rajapinnat_Toimitustietojen_hallinta_vx.x.pdf (x.x on versionumero). 2.2.4 Tapahtuman peruutus (vain Maksuturva) Palvelun avulla voi peruuttaa Maksuturva-toimeksiannon. Vastaussanomasta tulee vähintään tarkistaa, onnistuiko toimeksiannon peruutus (vastauskoodi 00). Rajapinnan kuvaus: SMT_Rajapinnat_TapahtumanPeruutus_vx.x.pdf (x.x on versionumero). 2.3 MAKSUTURVA-/EMAKSUT-PALVELUN KÄYTTÖÖNOTTO (LOMAKE) Palvelun avulla verkkokauppias voi ottaa Maksuturva/eMaksut-palvelun käyttöönsä. Verkkokauppias täyttää / täydentää palvelun käyttöönottolomakkeen tarvittavilta osin ja vahvistaa tilauksen joko pankkien tarjoamalla Tupas-allekirjoituksella tai pyytämällä paperisen sopimuksen allekirjoitettavaksi. Vastaussanomasta käy ilmi onnistuminen: luotiin uusi asiakkuus ja perustettiin uusi palvelu perustettiin uusi palvelu jo olemassa olevalle asiakkaalle uutta palvelua ei voitu perustaa, virhekoodi ja selite tarkentavat miksi Rajapinnan kuvaus: SMT_Rajapinnat_Kayttoonottolomake_vx.x.pdf (x.x on versionumero).
INTEGROINTIOHJE 6(9) 3 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 SHA-512 SHA-256 SHA-1 MD5 Algoritmi 512 -bittinen SHA-2 256 -bittinen SHA-2 160 -bittinen SHA-1 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.
INTEGROINTIOHJE 7(9) 4 VASTAUSTEN KÄSITTELY 4.1 Vastauksen tietojen tarkistaminen Verkkokaupasta Maksuturvalle/eMaksuille ja takaisin välitettävien tietojen osalta on ehdottomasti tarkistettava tietojen muuttumattomuus. Maksuturvan/eMaksujen 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. 5 TESTAUS Integraatiotyön alussa on suositeltavaa olla heti yhteydessä tekniseen tukeemme laittamalla viestiä osoitteeseen it-helpdesk@maksuturva.fi 5.1 Testiympäristö omilla testitunnuksilla Testitunnukset testiympäristöömme myönnetään ilman erillistä sopimusta, jotka voi tilata sähköisesti seuraavista osoitteista: Maksuturva: http://test1.maksuturva.fi/merchantsubscriptionbeginning.pmt emaksut: http://test1.maksuturva.fi/merchantsubscriptionbeginning.pmt?emaksut=true Tilinumerona voi käyttää esim. 123456-12345673. Pankkitunnistautuminen (TUPAS) ei ole tarpeellista. Testiympäristö toimii kuten tuotantoympäristökin, mutta mitään oikeita rahan käsittelyyn liittyviä toimintoja ei tehdä. Testiympäristössä käytetään verkkopankkien testiympäristöjä. Huom! Testiympäristön osoitteet ovat aina muodossa: http://test1.maksuturva.fi/<palvelu>.pmt 5.2 Rajapintatestaus yleisellä testitunnuksella tuotantoympäristössä Yllä kuvattuja Maksuturva-/eMaksut-toimeksiannon käsittelyyn liittyviä rajapintoja voi myös testata yleisellä testitunnuksella testikauppias jonka salainen avain on 11223344556677889900.
INTEGROINTIOHJE 8(9) Testitunnusta käytettäessä sovellus kääntyy ns. testausmoodiin ja käyttäytyy eri tavalla kuin normaalikäytössä. Testausmoodissa sovellus ei esim. tallenna mitään tietokantaan, vaan validoi vain sisään tulleet tiedot ja ilmoittaa joko virheistä tai muodostaa testattavan rajapinnan mukaan vastaussivun tai joissain tapauksissa XML -dokumentin. Yleisen testitunnuksen avulla on helpointa todentaa mm. tarkisteenlaskennan toimivuus. Testitunnusta käytettäessä sanomat lähetetään samaan osoitteeseen kuin tuotannossa (esim. https://www.maksuturva.fi/newpaymentextended.pmt). Yleistä testitunnusta on mahdollista käyttää myös testiympäristössä. 5.2.1 Maksamisen testaus (Maksuturva ja emaksut) 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. Jos esim. peruutus -paluuosoitteita ei sovellukselle välitetty, ei tätä linkkiä ole muodostettuna sivulla. 5.2.2 Tapahtuman tilan kyselyn testaus (Maksuturva ja emaksut) 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). 5.2.3 Toimitustietojen hallinnan testaus (vain Maksuturva) Tarkistetaan, että kenttien sisällöt vastaavat rajapintakuvausta ja että esim lähetystunnisteissa ei ole muotovirheitä. Ei osaa validoida seurantakoodeja täydellisesti ja hyväksyy tällä hetkellä käytännössä vain Itellan koodeja. Toimitustavan tunniste tulee olla ite89, tämä ei ole lopullinen tunniste millekään toimitustavalle, joten tunniste pitää muuttaa ennen varsinaista käyttöönottoa vastaamaan kulloinkin käytössä olevia toimitustapojen tunnisteita. Voimassa olevat toimitustapojen tunnisteet on listattu toimitustietojen hallinta -dokumentissa kohdassa 1.6. 5.2.4 Tapahtuman peruutus (vain Maksuturva) 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.
INTEGROINTIOHJE 9(9) 6 MATERIAALIT 6.1 MAKSUTURVA Tarvittava materiaali Maksuturva-palvelun käyttöönottoon ja käyttöön löytyy Suomen Maksuturvan kotisivuilta: https://www.maksuturva.fi/palvelut/kauppiaille/kauppiasmateriaali.html. 6.2 EMAKSUT Tarvittava materiaali emaksut-palvelun käyttöönottoon ja käyttöön löytyy emaksut-palvelun kotisivuilta (Integraatio ja materiaali): http://www.emaksut.fi/