lataa Maksuturvan maksupalvelun integrointiohjeet pdf

Transcription

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 | info@maksuturva.fi
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
4
/ 129
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
integrointiohjeet
5
/ 129
6
/ 129
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:
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:
8
/ 129
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.
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.
10
/ 129
integrointiohjeet
Tarkistusajan päätyttyä Maksuturva tilittää tilauksen summan verkkokaupalle ja palauttaa tai hyvittää
mahdollisen muutoksen mukaisen rahamäärän ostajalle.
integrointiohjeet
Esimerkkejä Tyytyväisyystakuun toiminnoista Verkko-ostajan palveluissa
Yksittäisten tuotteiden
palautus- ja peruutuslomake
11
/ 129
12
/ 129
integrointiohjeet
Koko tilauksen palautus- ja
peruutuslomake
Hinnanalennuksen esittämisen lomake
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.
14
/ 129
integrointiohjeet
Tilauksen tietojen erittely Verkkoostajan palveluissa tilauksen muutosten
vahvistuksen jälkeen.
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.
16
/ 129
integrointiohjeet
Esimerkki sertifikaattisivusta
integrointiohjeet
2. Maksuturva-palveluiden käyttöprosessi
17
/ 129
18
/ 129
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.
integrointiohjeet
19
/ 129
20
/ 129
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.
integrointiohjeet
2.2 Tilausten peruutukset ja muutokset
Alla joitakin esimerkkejä peruutus- ja palautusprosesseista.
21
/ 129
22
/ 129
integrointiohjeet
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.
24
/ 129
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.
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:
26
/ 129
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>
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)
/ 129
28
/ 129
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)
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.
29
/ 129
30
/ 129
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
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" />
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
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>
/ 129
32
/ 129
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.
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)
33
/ 129
34
/ 129
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
integrointiohjeet
• FI90 - Maksuturva-KV-tilisiirto
Tulevien ominaisuuksien tueksi: (pmt_escrow)
Uusi kenttä:
Uusia kenttiä tarkisteessa:
• 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ä
35
/ 129
36
/ 129
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=
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
P
P
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)
/ 129
38
/ 129
42.
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.
integrointiohjeet
3.3.2.1 Kenttien selitteet - Maksun välityksen tiedot
Kentän
Kenttä
Selite
numero
1.
Toiminnon tunniste
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
39
/ 129
40
/ 129
19.
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 tarkempi kuvaus.
kuvaus
37.
38.
Kokonaisluku. Kuinka monta ko. tilausrivillä olevaa tuotetta tilaus sisältää.
määrä
Ks. kohta “Tilauserittelyn laskentasäännöt”.
Tuotteen numero tai koodi verkkokaupassa. Valinnainen tieto.
tuotenumero
verkkokaupassa
39.
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 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”.
integrointiohjeet
42.
43.
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)
Tilausrivin
Tilausrivin tuotteeseen sovellettu ALV-prosentti. Desimaaliluku kahdella desimaalilla. Esim.
tuotteeseen
23,00.
sovellettu ALV-
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
41
/ 129
42
/ 129
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.
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.
44
/ 129
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)
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.
46
/ 129
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
AN128 P
integrointiohjeet
3.3.3.2 Kenttien selitteet - Maksun vastaussanoman tiedot
Kentän
Kenttä
Selite
numero
1.
Toiminnon
tunniste
2.
Sanoman
Maksusanoman sisällön määrittelyversio. Sama kuin vastaanotetussa sanomassa.
versio
3.
Maksun
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ä
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).
47
/ 129
48
/ 129
9.
integrointiohjeet
Escrow
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
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.
50
/ 129
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
KYSELYN PYYNNÖN TIEDOT (IN)
Uusia tietoja:
- pmtq_action (PAYMENT_STATUS_QUERY)
Uusia tietoja pyynnön tarkisteessa:
- 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:
- Tulevien ominaisuuksien tueksi (valinnainen): (pmtq_escrow)
- Valittu maksutapa (valinnainen): (pmtq_paymentmethod)
- 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
KYSELYN VASTAUSSANOMAN TIEDOT (OUT)
Uusia tietoja:
- pmtq_certification
- pmtq_externalcode1
- pmtq_externalcode2
- pmtq_externaltext
- pmtq_paymentstarttimestamp
- pmtq_paymentdate
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
51
/ 129
52
/ 129
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
pakollista tietoa ja V valinnaista.
integrointiohjeet
3.4.2.1 Kenttien selitteet - Tapahtuman tilan kyselyn tiedot
#
Kenttä
1. Toiminnon
Selite
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
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
8. Avaimen
sukupolvi
53
/ 129
54
/ 129
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
pmtq_action
AN50
P
2. Sanoman versio
pmtq_version
0005
AN4
P
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
integrointiohjeet
3.4.3.1 Kenttien selitteet - Tapahtuman tilan kyselyn
vastaussanoman tiedot
#
Kenttä
Selite
2. Sanoman versio
Tapahtuman kyselysanoman sisällön määrittelyversio.
Suomen Maksuturva Oy:n Kauppiaalle tunnistamista varten antama tunnus.
4. Maksun 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
55
/ 129
56
/ 129
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ä
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.
koodi 2
Käytetään virhetilanteissa välittämään ulkoisen maksupalveluntarjoajan virhekoodi 2.
Korttimaksuille Luottokunnan LKSRC –koodi.
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)
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
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ä
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)
/ 129
58
/ 129
integrointiohjeet
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)
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
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.
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ä.
/ 129
60
/ 129
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.
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
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.
62
/ 129
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
AN5
P
5.
Lisättävät toimitustiedot
pkg_adddeliveryinfo
AN50
P
6.
Poistettavat toimitustiedot
pkg_remdeliveryinfo
AN50
P
7.
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.
pkg_hashversion
AN10
P
12.
Tarkiste
pkg_hash
AN128
P
13.
Avaimen sukupolvi
pkg_keygeneration
N3
P
mittainen.
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.
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.
pkg_hashversion
AN10
P
12.
Tarkiste
pkg_hash
AN128
P
13.
Avaimen sukupolvi
pkg_keygeneration
N3
P
mittainen.
64
/ 129
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
Muoto
P/V
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
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
Tarkiste
Sanoman kentistä ja verkkokaupan salaisesta avaimesta laskettu tarkiste. Tarkiste lasketaan
seuraavista kentistä:
pkg_id
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
65
/ 129
66
/ 129
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
TRANS
Transpointin kirjattu lähetys
Tuotteet toimitetaan Transpointin pakettina. Toimitustietojen antaminen
KIITO
Kiitolinjan kirjattu lähetys
Tuotteet toimitetaan Kiitolinjan pakettina. Toimitustietojen antaminen
MYPAC
MyPack:n kirjattu lähetys
Tuotteet toimitetaan MyPack:n pakettina. Toimitustietojen antaminen
DBSCH
DB Schenkerin kirjattu lähetys
Tuotteet toimitetaan DB Schenkerin pakettina. Toimitustietojen antaminen
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ä.
asiakas on noutanut tilauksensa.
ODLVR
Oma kuljetus
Tuotteet toimitetaan asiakkaalla verkkokaupan omalla kuljetuksella.
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).
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.
67
/ 129
68
/ 129
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ä.
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.
69
/ 129
70
/ 129
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)
- pmtc_version
- pmtc_canceltype
- pmtc_cancelamount (jos canceltype = PARTIAL_REFUND /
PARTIAL_REFUND_AND_RETURN_OF_DELIVERIES)
MAKSUN PERUUTUKSEN VASTAUSSANOMAN TIEDOT (OUT)
- 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)
- pmtc_payeribanrefund
MAKSUN PERUUTUKSEN VASTAUSSANOMAN TIEDOT (OUT)
- errors –elementti, joka erittelee tiedoissa olleet virheet
Uusi vastauskoodi 90: Syöttötiedoissa oli virheitä
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
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.
72
/ 129
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.
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.
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.
14.
Tarkiste
Sanoman kentistä ja verkkokaupan salaisesta avaimesta laskettu tarkiste.
Tarkiste lasketaan tiedoista:
• pmtc_action
• pmtc_version
73
/ 129
74
/ 129
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
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
/ 129
76
/ 129
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
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
integrointiohjeet
3.7 Tilitysraporttien hakeminen
Tilitysraporttien hakemisen rajapintakuvaus, versio 1.1.1
Tämä palvelu mahdollistaa tilitysraportoinnin integroinnin verkkokauppaan.
77
/ 129
78
/ 129
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
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=
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.
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ä.
80
/ 129
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.
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
81
/ 129
82
/ 129
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.
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>
/ 129
84
/ 129
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>
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.
86
/ 129
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
sähköpostiosoite
puhelinnumero
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
katuosoite
postilokero
postinumero
postitoimipaikka
18. Verkkokauppayrityksen maa
srv_businesscountrycode
srv_billingaddress
srv_billingpobox
AN10
4
V
srv_billingpostalcode
AN5
5
V
srv_billingcity
AN40
1
V
laskutuskatuosoite
laskutuspostilokero
laskutuspostinumero
laskutuspostitoimipaikka
integrointiohjeet
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
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
yhteyshenkilön sähköpostiosoite
yhteyshenkilön puhelinnumero
yhteyshenkilön
matkapuhelinnumero
yhteyshenkilön faksinumero
laskutusyhteyshenkilön nimi
laskutusyhteyshenkilön
sähköpostiosoite
puhelinnumero
matkapuhelinnumero
faksinumero
39. Verkkokaupan teknisen
yhteyshenkilön nimi
yhteyshenkilön sähköpostiosoite
yhteyshenkilön puhelinnumero
yhteyshenkilön
matkapuhelinnumero
yhteyshenkilön faksinumero
44. Verkkokaupan Maksuturvamaksutavat
45. Verkkokaupan Maksuturvatoimitustavat
/ 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
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.
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. ”info@verkkokauppa.fi, (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.
laskutuspostilokero
Laskutusosoitteen postilokero.
21.
laskutuspostinumero
Laskutusosoitteen postinumero. Pakollinen jos laskutuskatuosoite annetaan.
22.
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.
89
/ 129
90
/ 129
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.
sähköpostiosoite
Yhteyshenkilön sähköpostiosoite
31.
puhelinnumero
Yhteyshenkilön puhelinnumero
32.
matkapuhelinnumero
Yhteyshenkilön matkapuhelinnumero
33.
faksinumero
Yhteyshenkilön faksinumero
34.
laskutusyhteyshenkilön nimi
Verkkokauppaa harjoittavan yrityksen laskutusyhteyshenkilö Suomen
Maksuturvalle.
35.
Laskutusyhteyshenkilön sähköpostiosoite. Pakollinen jos laskutusyhteyshenkilö
laskutusyhteyshenkilön sähköpostiosoite annetaan.
36.
laskutusyhteyshenkilön puhelinnumero
Laskutusyhteyshenkilön puhelinnumero. Pakollinen jos laskutusyhteyshenkilö
annetaan.
37.
matkapuhelinnumero
Laskutusyhteyshenkilön matkapuhelinnumero
38.
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.
puhelinnumero
Teknisen yhteyshenkilön puhelinnumero. Pakollinen jos tekninen
yhteyshenkilö annetaan.
42.
matkapuhelinnumero
Teknisen yhteyshenkilön matkapuhelinnumero
43.
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ä
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.
55.
Tarkiste
Sanoman kentistä ja verkkokaupan salaisesta avaimesta laskettu tarkiste.
Tarkiste lasketaan seuraavista kentistä:
• srv_webstorewww
56.
Avaimen sukupolvi
91
/ 129
92
/ 129
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.
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.
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.
virhekoodi
11.
virheen selite
integrointiohjeet
93
/ 129
3.8.2.1 Kenttien selitteet - Palvelun käyttöönoton vastaussanoman
tiedot
Kentän
Kenttä
Selite
numero
1.
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.
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.
Virheestä riippuvainen selite, joka edelleen selventää mistä virhe johtui (esim. luettelo
virheen selite
puuttuvista tai virheellisistä tiedoista).
94
/ 129
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.
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.
96
/ 129
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.
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:
98
/ 129
integrointiohjeet
Mikäli välitetyssä viestissä on virheitä, asia ilmoitetaan sivun yläreunassa:
Esimerkki virheestä viestin tarkisteessa:
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.
100
/ 129
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.
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).
102
/ 129
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
Salasana: 123456
Turvaluku: 123456
Turvaluku 2: 123456
LähiTapiola
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
Salasana: 7890
Avainluku: neljä mitä tahansa numeroa
POP Pankki
Salasana: 123456
Turvaluku: 123456
Turvaluku 2: 123456
S-Pankki
Säästöpankki
Salasana: 123456
Turvaluku: 123456
Turvaluku 2: 123456
integrointiohjeet
Ålandsbanken
103
/ 129
104
/ 129
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
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.
/ 129
106
/ 129
integrointiohjeet
5.1 Maksutapojen hakeminen (ostoskorikohtaisesti)
Esimerkki pyynnöstä (HTTP GET):
http://test1.maksuturva.fi/GetPaymentMethods.pmt?
https://www.maksuturva.fi/GetPaymentMethods.pmt?
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>
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>
107
/ 129
108
/ 129
integrointiohjeet
5.2 Dynaamisen kuva-aineiston hakeminen
Esimerkkejä löytyy rajapintakuvauksesta: Dynaamisen kuva-aineiston hakeminen
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="teemu.testaaja@maksuturva.fi" />
<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="Y" />

<input type="hidden" name="pmt_row_vat1"
<input type="hidden" name="pmt_row_discountpercentage1"
<input type="hidden" name="pmt_row_type1"
kuvaus" />
>
<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" />-->   
<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="teemu.testaaja@maksuturva.fi" />
<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"
vaihtoehtoinen brutolle-->
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="N" />
    
<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">
value="0002">
value="ABC123DE">
value="1998524_1">
<input type="hidden" name="pkg_adddeliveryinfo" value="JJFI12345612345123456">
value="Y">
value="N">
value="HTML">
value="">-->
value="SHA-256">
value="CA40867A33B5E6ACD525F89E398970A98C73F83AF9D02EAECCAFE2E2E92636E1">
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>
121
/ 129
122
/ 129
integrointiohjeet
<pkg_sellerid>ABC123DE</pkg_sellerid>
<pkg_id>1998524_1</pkg_id>
</pmtq>
Parametri pkg_id uupui pyynnöstä:
<pmtq>
<pkg_hash>null</pkg_hash>
<pkg_resulttext>pkg_id is a mandatory field</pkg_resulttext>
<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_hash>null</pkg_hash>
<pkg_resulttext>pkg_hash did not pass validation</pkg_resulttext>
<pkg_id>1998524_1</pkg_id>
</pmtq>
Esimerkki toimitustiedon muutospyynnöstä:
<form action="http://test1.maksuturva.fi/updateDeliveryInfo.pmt">
value="0002">
value="ABC123DE">
value="1998524_1">
<input type="hidden" name="pkg_remdeliverymethod" value="JJFI12345612345123456">
<input type="hidden" name="pkg_adddeliveryinfo"
value="JJFI12345612345234567">
value="N">
value="N">
value="XML">
value="">-->
value="SHA-256">
value="0B7591FAB0B9ED72FBDBB8B99F6C92BB82043BB03F056B4400BF71D71A939EC0">
value="1">
<input type="submit" value="Update delivery info">
</form>
Esimerkki muutospyynnön vastauksesta:
<pmtq>
<pkg_hash>CFDDF22DD538FFECF6F784F5E10C88A3704ED597E700DE6A36979D868574B8C4</pkg_hash>
integrointiohjeet
<pkg_id>1998524_1</pkg_id>
</pmtq>
Esimerkki toimitustiedon poistopyynnöstä:
<form action="http://test1.maksuturva.fi/deleteDeliveryInfo.pmt">
value="0002">
value="ABC123DE">
value="1998524_1">
<input type="hidden" name="pkg_remdeliverymethod" value="JJFI12345612345234567">
value="N">
value="N">
value="XML">
value="">-->
value="SHA-256">
value="CA40867A33B5E6ACD525F89E398970A98C73F83AF9D02EAECCAFE2E2E92636E1">
value="1">
<input type="submit" value="Delete delivery info">
</form>
Esimerkki poistopyynnön vastauksesta:
<pmtq>
<pkg_hash>CFDDF22DD538FFECF6F784F5E10C88A3704ED597E700DE6A36979D868574B8C4</pkg_hash>
<pkg_id>1998524_1</pkg_id>
</pmtq>
123
/ 129
124
/ 129
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):
value="CANCEL" />
value="0005" />
value="ABC123DE" />
value="1998524_1" />
value="568,10" />
value="EUR" />
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." />
value="OTHER" />
value="XML" />
value="SHA-256" />
value="3BB641AD9F2A26CCFBDAA36E58D25F011A9721D8F47570B07A7EBEE4DBE9F14F" />
value="1" />
</form>
123,00 € suuruinen tuotepalautuspyyntö (Osapalautus):
integrointiohjeet
125
/ 129
value="CANCEL" />
value="0005" />
value="ABC123DE" />
value="1998524_1" />
value="568,10" />
value="EUR" />
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" />
value="DEFEC" />
value="XML" />
value="SHA-256" />
value="E6495B9E0C05BE827F5BE97FA371193B793F59B4F2A4068165BD4DAEBA96E6F7" />
value="1" />
</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_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:
126
/ 129
integrointiohjeet
<pmtc>
<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>
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">
<timestamp>2014-10-16T14:14:51.000+03:00</timestamp>
<sellerId>ABC123DE</sellerId>
<hash>9B7ADF7633688101301E8F7617E996777D329A390F56FD135BE0122C46745BEC</hash>
<compensations>
<compensation>
<compensationType>SINGLE</compensationType>
<compensationDate>2014-10-14T00:00:00.000+03:00</compensationDate>
<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>
127
/ 129
128
/ 129
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:
<hash>E7BE30D784E97F98673E28F2570CF69AEE03810BE51E5EA773FD0E6ADAC99547</hash>
<compensations>
<compensation>
<compensationCode>10000000000000000000</compensationCode>
<compensationType>BUNDLE</compensationType>
<compensationDate>2014-10-14T14:27:12.000+03:00</compensationDate>
<grossAmount>1146.20</grossAmount>
<netAmount>1051.44</netAmount>
<refundedAmount>0.00</refundedAmount>
<orders>
<order>
<bundleCode>10000000000000000000</bundleCode>
</order>
<order>
<bundleCode>10000000000000000000</bundleCode>
</order>
</orders>
integrointiohjeet
129
</compensation>
</compensations>
Pyydetyltä aikaväliltä ei löydetty yhtään tilitystä:
<resultText>No events found.</resultText>
Pyydetty päivämääräväli oli liian suuri:
<resultText>Errors in: {[gc_enddate:the given interval is too big. Maximum allowed is one
month.]}</resultText>
/ 129

lataa Maksuturvan maksupalvelun integrointiohjeet pdf

Transcription

Similar documents

Maksupalvelun integrointiohje (pdf)

SANTANDER MAKSUTURVA - Santander Consumer Finance Oy

Maksaminen v4.1. Maksuturva ja eMaksut (pdf)

Kempact MIG 2530, Pulse 3000

Mazak Integrex 200 IV opas

Harjoittele unimaailman mestariksi