1. No category

Maksuturva- ja eMaksutpalvelun integrointiohje
Versio 1.4
2.1.2012
Suomen Maksuturva Oy High Tech Center, Tammasaarenkatu 1 | FIN-00180 Helsinki, Finland | [email protected]
INTEGROINTIOHJE
2(9)
2.1.2012
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
5
6
Vastauksen tietojen tarkistaminen............................................................................................................ 7
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
MATERIAALIT ...................................................................................................................................................... 9
6.1
MAKSUTURVA............................................................................................................................................ 9
6.2
EMAKSUT ................................................................................................................................................... 9
Suomen Maksuturva Oy High Tech Center, Tammasaarenkatu 1 | FIN-00180 Helsinki, Finland | [email protected]
INTEGROINTIOHJE
3(9)
2.1.2012
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ä.
Suomen Maksuturva Oy High Tech Center, Tammasaarenkatu 1 | FIN-00180 Helsinki, Finland | [email protected]
INTEGROINTIOHJE
4(9)
2.1.2012
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).
Suomen Maksuturva Oy High Tech Center, Tammasaarenkatu 1 | FIN-00180 Helsinki, Finland | [email protected]
INTEGROINTIOHJE
5(9)
2.1.2012
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).
Suomen Maksuturva Oy High Tech Center, Tammasaarenkatu 1 | FIN-00180 Helsinki, Finland | [email protected]
INTEGROINTIOHJE
6(9)
2.1.2012
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
Algoritmi
SHA-512
SHA-256
SHA-1
MD5
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.
Suomen Maksuturva Oy High Tech Center, Tammasaarenkatu 1 | FIN-00180 Helsinki, Finland | [email protected]
INTEGROINTIOHJE
7(9)
2.1.2012
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 [email protected]
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”.
Suomen Maksuturva Oy High Tech Center, Tammasaarenkatu 1 | FIN-00180 Helsinki, Finland | [email protected]
INTEGROINTIOHJE
8(9)
2.1.2012
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.
Suomen Maksuturva Oy High Tech Center, Tammasaarenkatu 1 | FIN-00180 Helsinki, Finland | [email protected]
INTEGROINTIOHJE
9(9)
2.1.2012
6
6.1
MATERIAALIT
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/
Suomen Maksuturva Oy High Tech Center, Tammasaarenkatu 1 | FIN-00180 Helsinki, Finland | [email protected]