Suomen Verkkomaksut Oy

Transkriptio

1 Maksujärjestelmän rajapintakuvaus Kanavamalli

2 Sisällysluettelo Versiohistoria...3 Kanavapalvelun kuvaus... 4 Rajapinnan kuvaus...5 Yleistä... 5 Lähetettävät kentät... 5 Kenttien selitteet... 7 Maksutiedon käsittely...10 Tarkisteen laskeminen Esimerkki tarkisteen laskemisesta Testaus Testitunnukset Esimerkki Avun saaminen asennuksiin... 16

3 Versiohistoria Päivämäärä Versio Muutokset Kanavamallin ensimmäinen rajapintakuvaus Korjattu esimerkki, -merkin enkoodaus URL:ss' on %7C eikä %C Päivitetty uusi palvelun osoite (action) Korjattu AUTHCODE esimerkissä - Korjattu maininta virheellisestä demokanavatunnuksesta Oikea tunnus on Lisätty taulukkoon puuttuva CHANNEL_ID arvo. Esimerkissä arvo oli huomioitu oikein. - Lisätty esimerkkiin AUTHCODE laskettuna molemmissa tuetuissa merkistöissä. Aiemmin tiiviste oli laskettu virheellisesti ISO merkistössä, vaikka esimerkissä kerrottiin käytettävän UTF-8 -merkistöä.

4 Kanavapalvelun kuvaus Suomen Verkkomaksujen myyntikanavamalli antaa myyntikanavalle mahdollisuuden tuoda haluttu maksukokonaisuus maksettavaksi Suomen Verkkomaksujen palvelussa. Yksittäinen maksukokonaisuus voi sisältää useiden eri yritysten myymiä tuotteita. Näiden yritysten on kuitenkin aina oltava Suomen Verkkomaksujen asiakkaita sekä hyväksynyt kyseisen myyntikanavan käytön. Jokaiselle palveluun tuotavalle tuoteriville määritellään yksikäsitteisesti yritys, joka kyseisen tuotteen myy. Myyntikanavamalli antaa myyntikanavalle mahdollisuuden määritellä tuoteriveittäin myyntikanavan veloittama provisio. Myyntikanava voi laskea provision vapaasti määrittämällään kaavalla. Myyntikanavan veloittaman provision laskentamalli määritellään Suomen Verkkomaksujen ja myyntikanavan välisessä sopimuksessa ja provision laskennassa tulee käyttää sovittua laskentatapaa. Myös Suomen Verkkomaksut veloittaa myyntikanavan ja Suomen Verkkomaksujen välisen sopimuksen mukaisen provision kaikista myyntikanavan kautta tuoduista maksuista. Myyntikanavan tulee huolehtia siitä, ettei palveluun välitetä sellaista tuotekokonaisuutta, että provisiot ylittävät tuotteiden summan. Myyntikanavaa käyttävät yritykset näkevät myyntikanavan kautta tulleet maksutapahtumat kauppiaspaneelissa. Yritykset näkevät myyntikanavan kautta tulleista maksuista ainoastaan yritystä itseään koskevat tuoterivit, jos maksukokonaisuus sisältää useampien yritysten tuotteita.

5 Rajapinnan kuvaus Yleistä Kanavamallin maksupalvelu toimii SSL-salatussa osoitteessa Maksukokonaisuuden tiedot lähetetään palveluun POST-kyselynä. Kun maksu on suoritettu, käyttäjä ohjataan takaisin verkkopalveluun verkkopalvelun määrittämään paluuosoitteeseen. Paluuosoitteeseen välitetään lisäksi parametrit, joiden perusteella maksu voidaan turvallisesti kuitata maksetuksi. Lähetettävät kentät Seuraavissa taulukoissa on kuvattu maksupalveluun lähetettävät tiedot. Taulukossa annetut pituudet ovat kenttien maksimiarvoja. Mikäli annettu pituus ylitetään, ei maksua hyväksytä. Kenttien muodoksi on merkitty taulukossa aina joko N, F tai AN. N tarkoittaa numeerista ja arvo on siten luku. F tarkoittaa desimaalilukua. Desimaaliluvuissa tuetaan korkeintaan kahden numeron tarkkuutta. Desimaalilukujen desimaalierottimena käytetään pistettä. AN tarkoittaa alfanumeerista, eli näiden kenttien tietosisältö voi olla mitä tahansa merkkejä. Kentät voidaan lähettää palveluun joko merkistössä UTF-8 tai ISO Merkistöjä ei voi käyttää sekaisin. Huomaa! Minkään kentän arvo ei saa sisältää -merkkejä (pipe, vertical bar). Arvot tulee poistaa tai korvata toisella merkillä ennen välittämistä Suomen Verkkomaksujen palveluun. Jos -merkkejä halutaan tuoda paluuosoitteissa, suosittelemme tuomaan osoitteen URL-enkoodattuna (Esim. PHP-kielessä funktio urlencode). Erityisesti -merkki tulee tällöin korvata merkeillä %7C. Kenttien pakollisuus on kerrottu kentässä Pakollinen/Valinnainen. Valinnaisista kentistä erityisesti NOTIFY_ADDRESS-kentän tarjoamaa toiminnallisuutta kuitenkin suositellaan käytettäväksi aina. Kenttä Tiedon nimi Pituus max. Muoto Pakollinen / Valinnainen Kanavatunnus CHANNEL_ID 11 N P Tilausnumero ORDER_NUMBER 64 AN P Valuutta CURRENCY 3 AN P Palautusosoite / Onnistunut maksu Palautusosoite / Peruutunut maksu RETURN_ADDRESS 255 AN P CANCEL_ADDRESS 255 AN P Huomautusosoite NOTIFY_ADDRESS 255 AN P Rajapinnan versio VERSION 2 N P Kulttuurikoodi CULTURE 5 AN V Maksutavan esivalinta METHOD_PRESELECT 2 AN V

6 Kenttä Tiedon nimi Pituus max. Muoto Pakollinen / Valinnainen Tunnistekoodi AUTHCODE 32 AN P Maksajan puhelinnumero CONTACT_TELNO 64 AN V Maksajan CONTACT_CELLNO 64 AN V matkapuhelinnumero Maksajan sähköpostiosoite CONTACT_ 255 AN P Maksajan etunimi CONTACT_FIRSTNAME 64 AN P Maksajan sukunimi CONTACT_LASTNAME 64 AN P Maksajan yritys CONTACT_COMPANY 128 AN O Maksajan postiosoite CONTACT_ADDR_STREET 128 AN P Maksajan postinumero CONTACT_ADDR_ZIP 16 N P Maksajan postitoimipaikka CONTACT_ADDR_CITY 64 AN P Maksajan kotimaa CONTACT_ADDR_COUNTRY 2 AN P Arvonlisäveron sisältyminen INCLUDE_VAT 1 N P Tuoterivien määrä ITEMS 8 N P Lisäksi tilaukseen liitetyt tuotteet voidaan tuoda Suomen Verkkomaksujen palveluun seuraavilla toistuvilla kentillä. Kenttä Tiedon nimi Pituus max. Muoto Pakollinen / Valinnainen Tuotteen nimi ITEM_TITLE[X] 255 AN P Tuotenumero ITEM_NO[X] 16 AN V Tuotteiden määrä ITEM_AMOUNT[X] 10 F P Tuotteen hinta ITEM_PRICE[X] 10 F P Tuotteen veroprosentti ITEM_TAX[X] 10 F P Tuotteen kauppias-id ITEM_MERCHANT_ID[X] 8 N P Tuotteen kanavaprovisioluokan ID ITEM_CP[X] 10 F V Tuotteen alennus-prosentti ITEM_DISCOUNT[X] 10 F V Tuotetyyppi ITEM_TYPE[X] 2 N V

7 Kenttien selitteet Kenttä Kanavatunnus Selite Kanavatunnus on :n myyntipaikalle antama tunniste. Kanavatunnus muodostuu pelkistä numeroista. (pakollinen) Tilausnumero Tilausnumero on tilauksen yksilöivä merkkijono. (pakollinen) Valuutta Maksun valuutta. Vain EUR sallittu. (pakollinen) Palautusosoite / Onnistunut maksu Palautusosoite / Peruutunut maksu Osoite johon ohjataan sen jälkeen kun maksu on suoritettu onnistuneesti Suomen maksupalvelu Oy:lle. (pakollinen) Osoite, johon ohjataan jos maksu on peruuntunut tai epäonnistunut. (pakollinen) Huomautusosoite Osoite, jota kutsutaan, kun maksu merkitään onnistuneeksi. Tätä osoitetta kutsutaan ohjelmallisesti samoilla GET-parametreillä kuin RETURN_ADDRESS:ia kun maksu on suoritettu. (pakollinen) Versio Maksurajapinnasta käytettävän version numero. Kanavarajapinnan versio on 1. (pakollinen) Kulttuuri Maksutavan esivalinta Tunnistekoodi Maksajan puhelinnumero Kulttuuri vaikuttaa maksutapavalintasivun oletuskieleen ja summien esitystapaan. Käytettävissä on kulttuurit fi_fi, "sv_se" ja "en_us. Oletuskulttuuri on fi_fi. (vapaaehtoinen) Tämä kenttä ei ole toistaiseksi käytössä. Kenttä on kuitenkin huomioitava tyhjänä merkkijonona AUTHCODE-arvon laskennassa. Tunnistekoodi on MD5-algoritmillä merkkijonosta laskettu tiivistearvo, jonka avulla estetään väärinkäytöksiä. Laskennassa käytetään kaikkia tilauksen tietoja sekä kanavalle annettua erillistä ns. kanavavarmennetta. Katso laskentatapa esimerkistä. (pakollinen) Maksajan puhelinnumero (vapaaehtoinen) Maksajan matkapuhelinnumero Maksajan etunimi Maksajan matkapuhelinnumero (vapaaehtoinen) Maksajan etunimi (pakollinen) Maksajan sukunimi Maksajan sukunimi (pakollinen) Maksajan yritys Maksajan yritys (vapaaehtoinen)

8 Kenttä Maksajan postiosoite Selite Maksajan postiosoite eli lähiosoite (pakollinen). Maksajan postinumero Maksajan postinumero (pakollinen) Maksajan postitoimipaikka Maksajan postitoimipaikka (pakollinen) Maksajan kotimaa Arvonlisäveron sisältyminen Tuotteiden määrä Maksajan kotimaa. Tieto toimitetaan ISO standardin mukaisesti kaksinumeroisena merkkijonona. Esimerkiksi Suomi on FI ja Ruotsi on SE. Merkkien kirjainkoolla ei ole merkitystä. (pakollinen) Arvonlisäveron sisältyminen -kenttä kertoo sisältyykö tuoteriveissä ilmaistu hinta arvonlisäveron. Arvo 1 tarkoittaa arvonlisäveron sisältyvän tuotuun hintaan ja 0, että arvonlisävero lisätään annettuihin hintoihin. Käytä siis arvoa 1, jos tuotteiden hinnat on tallennettu verkokaupassa arvonlisäverollisina ja arvoa 0 jos hinnat on tallennettu arvonlisäverottomina. (pakollinen) Tuoterivien määrä. Vastaavat tuoterivit on oltava mukana seuraavan taulukon mukaisesti. (pakollinen) Seuraavassa on listattu tuotetietojen selitykset. Kenttä Selite Tuotteen nimi Vapaamuotoinen nimi tuotteelle. (pakollinen) Tuotenumero Tuotteiden määrä Tuotteen hinta Tuotteen veroprosentti Vapaaehtoinen tuotenumero, joka näytetään kauppiaspaneelissa tuotteen kohdalla. Tämän käyttö saattaa helpottaa oikeaan tuotteeseen kohdistamista. (vapaaehtoinen) Jos tilaus sisältää useita samoja tuotteita, voidaan tässä kertoa tuotteiden määrä, jolloin jokaista tuotetta ei tarvitse tuoda omana rivinään. Yleensä tässä tuodaan siis arvo 1. (pakollinen) Yhden tuotteen hinta. Jos kentässä INCLUDE_VAT=0, on tämä hinta arvonlisäveroton hinta. Jos INLUCDE_VAT=1, on tämä hinta arvonlisäverollinen. Hinnan tulee olla aina positiivinen luku. Alennukset voidaan tuoda tuotekohtaisella alennusprosentti-kentällä. (pakollinen) Tuotteelle käytetty veroprosentti. Suomessa arvonlisävero useimmille tuotteille 22%. (pakollinen) Tuotteen kauppias Tuotteen kanavarovisioluokan ID Yksi Suomen Verkkomaksujen palveluun tuotava maksu voi sisältää useiden eri yritysten tuotteita. Jokaisella tuoterivillä tuodaan tuotteen myyjän kauppiastunnus. (pakollinen) Myyntikanavalle voidaan määrittää tarvittaessa useita provisioluokkia. Jokaiselle tuotteelle voidaan määrittää käytettävä provisioluokka erikseen. Tämä mahdollistaa esimerkiksi eri hinnoittelun premium-asiakkaille tai halvemman provision arvokkaammille tuotteille. Suomen Verkkomaksut toimittaa sopimuksen mukaiset provisioluokkien ID:t myyntikanavalle. (pakollinen)

9 Kenttä Selite Tuotteen alennusprosentti Jos tuotteesta on myönnetty alennus, voidaan tässä kentässä tuoda alennusprosentti, joka on luku Oletusarvo alennukselle on 0. (vapaaehtoinen) Tuotetyyppi Tuoteriville voidaan määrittää tyyppi. Tyyppi 1 tarkoittaa normaalia tuoteriviä. Postikuluille voidaan käyttää arvoa 2 ja käsittelykuluille arvoa 3. Oletusarvo kentälle on 1. (vapaaehtoinen)

10 Maksutiedon käsittely Kun asiakas on suorittanut maksun verkkopankissa, ohjataan käyttäjä takaisin siihen osoitteeseen, joka kentässä RETURN_ADDRESS on määritelty. Jos maksu on epäonnistunut tai peruuntunut, asiakas ohjataan vastaavasti CANCEL_ADDRESS -kentässä määriteltyyn osoitteeseen. Lisäksi käytössä on huomautusosoite NOTIFY_ADDRESS, jota kutsutaan ohjelmallisesti kun Suomen Verkkomaksut kirjaa maksun onnistuneeksi. Tyypillisesti NOTIFY_ADDRESS-osoitetta kutsutaan välittömästi ennen RETURN_ADDRESS-osoitteeseen siirtymistä. On mahdollista, että asiakas ei jostain syystä palaa pankin palvelusta Suomen Verkkomaksujen palveluun. Tällöin maksu vahvistetaan yhden pankkipäivän viiveellä Suomen Verkkomaksujen toimesta ja maksun vahvistamisen yhteydessä tehdään NOTIFY_ADDRESSosoitteeseen kutsu. NOTIFY_ADDRESS-osoitteen kutsu sisältää vastaavat GET-parametrit kuin RETURN_ADDRESS-osoitteeseen siirtyminen. Osoitteisiin RETURN_ADDRESS ja CANCEL_ADDRESS siirtymisessä sekä NOTIFY_ADDRESS-osoitteen ohjelmallisessa kutsussa on mukana alla kuvatut GET-parametrit, joista maksun oikeellisuus tulee tarkistaa. Kenttä Tieto Tiedon nimi 1. Tilausnumero ORDER_NUMBER 2. Aikaleima TIMESTAMP 3. Maksutunnus PAID 4. Tarkistekenttä RETURN_AUTHCODE Seuraavassa listauksesa on kuvattu näiden kenttien tarkoitus. Kenttä Tilausnumero Aikaleima Maksutunnus Selite Sama tilausnumero, joka lähetettiin aiemmin maksujärjestelmään. Tilausnumero yksilöi jokaisen maksun. Suomen Verkkomaksujen tuottama aikaleima, jota käytetään tarkisteen laskemiseen. Aikaleima on UNIX-muodossa, joka lasketaan sekunteina vuorokauden vaihtumisesta. Suomen Verkkomaksujen tuottama tunnus joka palautetaan vain onnistuneen maksun paluutiedoissa. Tarkistekenttä Tarkistekenttä sisältää maksupalvelun laskeman hash-arvon, johon kauppias voi verrata itse laskemaansa arvoa. Mikäli kauppiaan laskema arvo on sama kuin maksupalvelun ilmoittama, on tieto maksusta tullut perille muuttumattomana. Tarkiste voi olla sama, vaikka maksu olisikin epäonnistunut tai peruuntunut.

11 Tarkisteen laskeminen Tarkiste lasketaan suorittamalla seuraavat vaihdeet: 1. Muodostetaan merkkijono yhdistämällä kentät tilausnumero, aikaleima, maksutunnus ja kauppiasvarmenne tässä järjestyksessä. Kaikkien mainittujen kenttien väliin sijoitetaan -merkki (pipe, vertical bar). Epäonnistuneen maksun tapauksessa paluutiedot eivät sisällä arvoja maksutunnus ja maksutapa näitä ei myöskään huomioida tarkisteen laskennassa. 2. Lasketaan muodostetusta merkkijonosta MD5-tiiviste 3. Huomioidaan saatu arvo 32-merkkisenä heksadesimaalisena esityksenä ja korvataan pienet kirjaimet suurilla. Esimerkki tarkisteen laskemisesta Tilausnumero: Aikaleima: Maksutunnus: Maksutapa: 1 Kanavavarmenne: F4SDGF23FS Muodostetaan merkkijono: F4SDGF23FS Md5-funktiolla merkkijonosta laskettu hash-arvo: Muutetaan pienet kirjaimet isoiksi: 65fd308175c2a cacecf FD308175C2A CACECF70465 Mikäli laskettu tarkiste on sama kun maksupalvelusta saatu arvo (RETURN_AUTHCODE), on maksukuittaus saapunut virheettömänä.

12 Testaus Testitunnukset Kanavamallia voidaan testata allaolevilla tunnuksilla. Kanavatunnus (CHANNEL_ID): 123 Kanavavarmenne: Lisäksi jokaiselle testitilauksessa palveluun tuodulle tuotteelle on käytettävä kauppiastunnusta Kanavamallin provisioluokan ID on testauksessa aina arvo 1. Esimerkki Tässä on listattu esimerkkikoodi painikkeelle, joka lähettää maksun Suomen Verkkomaksujen palveluun. <form action=" method="post"> <input name="channel_id" type="hidden" value="123"> <input name="order_number" type="hidden" value=" "> <input name="currency" type="hidden" value="eur"> <input name="return_address" type="hidden" value=" <input name="cancel_address" type="hidden" value=" <input name="notify_address" type="hidden" value=" <input name="version" type="hidden" value="1"> <input name="culture type="hidden" value="fi_fi"> <input name="contact_telno" type="hidden" value=" "> <input name="contact_ " type="hidden" <input name="contact_firstname" type="hidden" value="matti"> <input name="contact_lastname" type="hidden" value="meikäläinen"> <input name="contact_company" type="hidden" value="testi Oy Ab"> <input name="contact_addr_street" type="hidden" value="testikatu 1"> <input name="contact_addr_zip" type="hidden" value="43210"> <input name="contact_addr_city" type="hidden" value="jyväskylä"> <input name="contact_addr_country" type="hidden" value="fi"> <input name="include_vat" type="hidden" value="1" /> <input name="items" type="hidden" value="2"> <input name="item_title[0]" type="hidden" value="esimerkkituote 1"> <input name="item_no[0]" type="hidden" value="12345"> <input name="item_amount[0]" type="hidden" value="1"> <input name="item_price[0]" type="hidden" value="10.00"> <input name="item_tax[0]" type="hidden" value="22.00"> <input name="item_merchant_id[0]" type="hidden" value="13466"> <input name="item_cp[0]" type="hidden" value="1"> <input name="item_discount[0]" type="hidden" value="0"> <input name="item_type[0]" type="hidden" value="1">

13 <input name="item_title[1]" type="hidden" value="esimerkkituote 2"> <input name="item_no[1]" type="hidden" value="12346"> <input name="item_amount[1]" type="hidden" value="2"> <input name="item_price[1]" type="hidden" value="5.00"> <input name="item_tax[1]" type="hidden" value="22.00"> <input name="item_merchant_id[1]" type="hidden" value="13466"> <input name="item_cp[1]" type="hidden" value="1"> <input name="item_discount[1]" type="hidden" value="20.00"> <input name="item_type[1]" type="hidden" value="1"> <input name="authcode" type="hidden" value="657bae6236f0fb709388fabb6467bfdb"> <input type="image" src=" </form> Ylläolevassa listauksessa viimeinen hidden-kenttä, AUTHCODE, on laskettu alla kuvatulla tavalla. Yhdistetään kaikki kentät järjestyksessä, jossa ne on mainittu dokumentaatiossa. Kentät yhdistetään asettamlla -merkki (pipe, vertical bar) kenttien väliin. Jos jotakin kenttää ei lähetetä, asetetaan kentän kohdalle laskennassa tyhjä merkkijono, jolloin merkkijonoon tulee kaksi tai useampia peräkkäisiä -merkkejä. Ensimmäisenä kenttänä laskennassa huomioidaan kanavavarmenne. AUTHCODE muodostetaan tästä merkkijonosta laskemalla MD5-summa. Saatu arvo muutetaan heksadesimaaliseen, 32-merkkiä pitkään esitysmuotoon ja merkkijonosta muutetaan pienet kirjaimet isoiksi. Huomaa! Tässä esimerkissä laskenta tehdään UTF-8 -merkistössä. Suomen Verkkomaksujen palvelu tukee UTF-8- ja ISO merkistöjä. AUTHCODE:n laskenta on aina suoritettava samassa merkistössä, missä tiedot lähetetään Suomen Verkkomaksujen palveluun. Suomen Verkkomaksujen palvelu tunnistaa vastaanotetusta aineistosta automaattisesti käytetyn merkistön ja käyttää varmenteen laskennassa samaa tunnistettua merkistöä. Ylläolevassa esimerkissä kenttien arvot ovat seuraavat:

14 Kanavavarmenne Kanavatunnus 123 Tilausnumero Valuutta Paluuosoite/onnistunut maksu Paluuosoite/epäonnistunut maksu Huomautusosoite Versionumero 1 Kulttuuri EUR fi_fi Maksajan puhelinnumero Maksajan matkapuhelinnumero Maksajan sähköpostiosoite Maksajan etunimi Maksajan sukunimi Maksajan yritys esimerkki@esimerkki.fi Matti Meikäläinen Testi Oy Ab Maksajan lähiosoite Testikatu 1 Maksajan postinumero Maksajan postitoimipaikka Maksajan kotimaa Arvonlisäveron sisältyminen 1 Tuoterivien määrä 2 Jyväskylä Tuote #1, otsikko Esimerkkituote 1 Tuote #1, numero Tuote #1, määrä 1 Tuote #1, hinta Tuote #1, veroprosentti Tuote #1, kauppiastunnus Tuote #1, kanavaprovision ID 1 Tuote #1, alennusprosentti 0 Tuote #1, tyyppi 1 Tuote #2, otsikko Esimerkkituote 2 Tuote #2, numero Tuote #2, määrä 2 Tuote #2, hinta 5.00 Tuote #2, veroprosentti FI

15 Tuote #2, kauppiastunnus Tuote #2, kanavaprovision ID 1 Tuote #2, alennusprosentti Tuote #2, tyyppi 1 Nyt AUTHCODE:n laskemiseen käytettävä merkkijono saadaan yhdistämällä edelliset kentät: EUR fi_fi esimerkki@esimerkki.fi Matti Meikäläinen Testi Oy Ab Testikatu Jyväskylä FI 1 2 Esimerkkituote Esimerkkituote Tästä lasketaan MD5-tiiviste: 29322dbeebc3c86b1e1b1f31a007b4dc (ISO : 657bae6236f0fb709388fabb6467bfdb) Muutetaan kirjaimet isoiksi, jolloin saadaan lopullinen varmenne: 29322DBEEBC3C86B1E1B1F31A007B4DC (ISO : 57BAE6236F0FB709388FABB6467BFDB)

16 Avun saaminen asennuksiin Voit soittaa tekniseen tukeemme numeroon tai voit lähettää sähköpostia osoitteeseen: